[Bf-python] documentation markup proposal

[Michael Reimpell]

At the moment, BPy agrees on (slightly enhanced) javadoc markup for the Python 
API documentation. It is written in .py files located at 
source/blender/python/api2_2x/doc and can be processed via epydoc. 

In contrast, there is no common documentation markup for the underlying C/C++ 
code. Skimming through the Blender source you see that javadoc is used 
occasionally, but most of the functions either come without documentation or 
with a short plain text description. Working with the blender source, you 
will find yourself reading other people's functions line by line just to 
figure out what they do.

I think this time could be better spend with actual development and therefore 
propose to use javadoc markup from now on. Even if you can't build a complete 
API documentation, since not all of the old code is documented this way, 
using a documentation markup urges you to write a short explanation of every 
argument and return value. This way developer documentation will be much more 
complete and the time spent reading functions line by line will be reduced 
significantly. In my opinion, javadoc is the natural choise for the markup 
language, since it is already used in BPy's .py files and can be processed 
with GPL tools like doxygen.

Regards,
Michael