[Bf-committers] Doxygen project

[Ton Roosendaal]

Hi,


>> Right now, my opinion is simple:
>>
>> - doxify the classes/headers and external API only
>> - no doxy comments inside the code, but restrict to
>> .h files
>> - only document what would give additional added
>> value.
>> - Code readability and layout should never be
>> sacrified
>>
>> -Ton-
>
> I have no problem with this, or with what Nathan
> wrote, except for one thing: source/blender/src .
> This is where I personally have the most difficult
> time understanding the code (am I the only one?).

And that's especially the code to leave alone, at least for a while...  
you can find the associated include files in the  
source/blender/include/ BTW.

I noticed an attempt to doxy mainqueue.c, which contains experimental  
code which was supposed to start a restructuring, something that was  
never finished.
Doxy conventions really don't fit this code. Currently I am fixing all  
little quirks in the OSX port, which closely relate to this code. While  
getting more confident with it again, I'll decide to either:

- write docs!
- restructure it all!

With the emphasis on the last... i've got ideas to build it from ground  
up again. Don't forget that this low level interface/screen code in  
Blender was originally written for irix windows (pre-opengl), then  
converted to opengl, and got polluted with Glut and later on attached  
to Ghost. The inner structure now radically should be cleaned up, and  
nicely attached to ghost again. That's the only way to get it to  
understanding.

Please rewind the doxy for mainqueue.c or other c files you did here.
Also, do not document with phrases like:

  * The documentor (me) doesn't know the full description of
  * the fields of the QEvent structure, and the parameters to the
  * functions (event, val, ascii).  The comments should be updated
  * with more detailed descriptions of what is stored in each one.

It confuses me completely. Especially for the reconstruction I really  
only need comments from the original coders, who *really* knew what or  
why they wrote.
And for other documentaton; only write what you know 100% for sure, and  
adds to the code.

--------------EXAMPLE:
/**
  *	\struct QEvent
  *	\brief  This is the definition for the event queue datastructure
  */
typedef struct {
	/**
	 * \var unsigned short event
	 * \brief holds the event type
	 */
	unsigned short event;
	/**
	 * \var short val
	 */
	short val;
	/**
	* \var char ascii
	*/
	char ascii;
} QEvent;
---------------------------

Please don't do this! But instead:

------------------------------
/**
  *	\struct QEvent
  *	\brief  holding values coming from Ghost event handlers. Still  
experimental. (ton)
  */
typedef struct {
	unsigned short event;
	short val;
	char ascii;
} QEvent;
-----------------------------

That's something that informs, and keeps it readable.
I also like to add a name to comments, for reference who to complain to.

And if you don't know what it really means, just write nothing.
Leave out text like "This is the definition for the event queue  
datastructure" which has hardly no real meaning:
- we already know it is a definition
- also that it is a data structure
And only rises questions like: used where? whatfor? how?

Sorry for the rant, not meant negative! :)

-Ton-

------------------------------------------------------------------------ 
--
Ton Roosendaal  Blender Foundation ton@blender.org  
http://www.blender.org