[Bf-committers] Code documentation (subsurf.c)

[Ton Roosendaal]

Hi Richard,

We've discussed the doxy topic last sunday at the weekly irc meeting.  
I'll report on that today as well. Apart from the outcome of this  
discussion, I think the efforts you do to doxify the code goes beyond  
the targets we'll support right now.

Documenting is important, nobody disagrees with that. But the methods  
or conventions we'll use for Blender are hard to define. For two  
reasons:
- finding something everyone agrees on
- finding something everyone actually *does*

Especially the last topic is relevant. Doxyfying the code as you did  
with subsurf.c is a very personal thing. Some might like it, others can  
completely detest the way the code is made unreadable with noisy  
comments. To be honest with you, I belong to the last category! I found  
subsurf.c one of the rare code pieces in Blender (not written by me)  
that were quite well structured, and easy to comprehend. Comments - for  
me - should never just repeat or replace code, but instead add hidden  
thoughts or considerations from the coder why he did something.

This is for example what I call 'noise':

/**
  * \brief Copy a 2 dimensional vector.
  *
  * @param t The new copy.
  * @param a The vector to copy.
  * @return The new copy.
  */

Such a description is very hard to understand, and doesn't tell me what  
goes on.
The actual code however, is completely self-documenting:

static float *Vec2Cpy(float *t, float *a) {
	t[0]= a[0];
	t[1]= a[1];
	return t;
}

The 'static' here clearly states its an internal function as well. Only  
needed to understand when you work on the subsurf code itself.

I can imagine Doxygen is useful for code when a developer decides to  
use it from scratch. Building a structure with comments first, and  
reveiling a design & structure that way. It can also be useful for real  
libraries, where the external available calls are clearly documented  
that way. For inside of the code, it's really a different topic.
For developers who participate in Blender projects, it's free to decide  
to use Doxy when they work on new code. But for the time being we won't  
elevate that to an enforced standard.

-Ton-


On Saturday, Jan 3, 2004, at 22:44 Europe/Amsterdam, Richard Berry  
wrote:

> I've been going over Blender's code for a few months now and have been  
> adding Doxygen comments to various bits. I've finished documenting  
> source/blender/blenkernel/intern/subsurf.c and put the patch at:
>
> http://www.warwick.ac.uk/student/R.J.Berry/subsurf.diff
>
> The file with the patch applied is at:
>
> http://www.warwick.ac.uk/student/R.J.Berry/subsurf.c
>
> Someone with more experience with the interaction between the subsurf  
> / mesh / display list code (I'm still getting my head around this)  
> should go over the comments for the following functions:
> hypermesh_to_displist
> subsurf_subdivide_to_displist
> subsurf_make_editmesh
> subsurf_make_mesh
> subsurf_to_mesh
> subsurf_mesh_to_displist
>
> Also, the HyperVert, HyperEdge and HyperFace structures contain some  
> members that I haven't documented. Basically the flag parameter and a  
> union that involves edit faces.
>
> I was also wondering where if I should put the function documentation  
> for globally available functions (i.e. those declared in  
> BKE_subsurf.h): with the interface (BKE_subsurf.h) or with the  
> implementation (subsurf.c). I think I've seen this with some of the  
> Doxygen comments I've looked at. I put it with the implementation as  
> this makes more sense for when changing code and updating  
> documentation (and can applied as one patch).
>
> Hopefully the comments should be similar to what has been previously  
> mentioned in the guidelines and various mailing list threads but any  
> comments, corrections or beatings due to glaring idiocy are  
> appreciated.
>
> I was mere seconds from sending this when I received Alex's post to  
> the "doxygen updates" thread which lists BKE_subsurf.h as one of the  
> header files that needs commenting. Should I generate / copy the  
> comments that I've already done for this?
>
> r i c k
> _______________________________________________
> Bf-committers mailing list
> Bf-committers@blender.org
> http://www.blender.org/mailman/listinfo/bf-committers
>
>
------------------------------------------------------------------------ 
--
Ton Roosendaal  Blender Foundation ton@blender.org  
http://www.blender.org