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

[Richard Berry]

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