extras: protoc: document protoc trickiness

I tried to quickly go through the protoc source to find how the include
paths are interpreted, but I'm sleepy now.

waflib/extras/protoc.py

@@ -10,6 +10,8 @@ from waflib.TaskGen import extension
 """
 A simple tool to integrate protocol buffers into your build system.
 
+Example::
+
     def configure(conf):
         conf.load('compiler_cxx cxx protoc')
 
@@ -20,9 +22,20 @@ A simple tool to integrate protocol buffers into your build system.
                 include  = '. proto',
                 target   = 'executable') 
 
+Notes when using this tool:
+
+- protoc command line parsing is tricky.
+
+  The generated files can be put in subfolders which depend on
+  the order of the include paths.
+
+  Try to be simple when creating task generators
+  containing protoc stuff.
+
 """
 
 class protoc(Task):
+	# protoc expects the input proto file to be an absolute path.
 	run_str = '${PROTOC} ${PROTOC_FLAGS} ${PROTOC_ST:INCPATHS} ${SRC[0].abspath()}'
 	color   = 'BLUE'
 	ext_out = ['.h', 'pb.cc']