style cleanup: header comments, use more doxy compat formatting

1 files changed, 72 insertions, 72 deletions

diff --git a/source/blender/blenkernel/BKE_DerivedMesh.h b/source/blender/blenkernel/BKE_DerivedMesh.h
index c7ddab47952..64512dcaac8 100644
--- a/source/blender/blenkernel/BKE_DerivedMesh.h
+++ b/source/blender/blenkernel/BKE_DerivedMesh.h
@@ -28,12 +28,14 @@
 #ifndef __BKE_DERIVEDMESH_H__
 #define __BKE_DERIVEDMESH_H__
 
-/*
+/**
  * Basic design of the DerivedMesh system:
  *
  * DerivedMesh is a common set of interfaces for mesh systems.
  *
- * There are three main mesh data structures in Blender: Mesh, CDDM, and BMesh.
+ * There are three main mesh data structures in Blender:
+ * #Mesh, #CDDerivedMesh and #BMesh.
+ *
  * These, and a few others, all implement DerivedMesh interfaces, 
  * which contains unified drawing interfaces, a few utility interfaces, 
  * and a bunch of read-only interfaces intended mostly for conversion from 
@@ -67,7 +69,6 @@
  *       as it is and stick with using BMesh and CDDM.
  */
 
-
 #include "DNA_customdata_types.h"
 #include "DNA_meshdata_types.h"
 
@@ -151,7 +152,7 @@ typedef enum DMDirtyFlag {
 
 typedef struct DerivedMesh DerivedMesh;
 struct DerivedMesh {
-	/* Private DerivedMesh data, only for internal DerivedMesh use */
+	/** Private DerivedMesh data, only for internal DerivedMesh use */
 	CustomData vertData, edgeData, faceData, loopData, polyData;
 	int numVertData, numEdgeData, numTessFaceData, numLoopData, numPolyData;
 	int needsFree; /* checked on ->release, is set to 0 for cached results */
@@ -162,10 +163,10 @@ struct DerivedMesh {
 	float auto_bump_scale;
 	DMDirtyFlag dirty;
 
-	/* calculate vert and face normals */
+	/** Calculate vert and face normals */
 	void (*calcNormals)(DerivedMesh *dm);
 
-	/* recalculates mesh tessellation */
+	/** Recalculates mesh tessellation */
 	void (*recalcTessellation)(DerivedMesh *dm);
 
 	/* Misc. Queries */
@@ -177,7 +178,7 @@ struct DerivedMesh {
 	int (*getNumLoops)(DerivedMesh *dm);
 	int (*getNumPolys)(DerivedMesh *dm);
 
-	/* copy a single vert/edge/tessellated face from the derived mesh into
+	/** Copy a single vert/edge/tessellated face from the derived mesh into
 	 * *{vert/edge/face}_r. note that the current implementation
 	 * of this function can be quite slow, iterating over all
 	 * elements (editmesh)
@@ -186,7 +187,7 @@ struct DerivedMesh {
 	void (*getEdge)(DerivedMesh *dm, int index, struct MEdge *edge_r);
 	void (*getTessFace)(DerivedMesh *dm, int index, struct MFace *face_r);
 
-	/* return a pointer to the entire array of verts/edges/face from the
+	/** Return a pointer to the entire array of verts/edges/face from the
 	 * derived mesh. if such an array does not exist yet, it will be created,
 	 * and freed on the next ->release(). consider using getVert/Edge/Face if
 	 * you are only interested in a few verts/edges/faces.
@@ -197,7 +198,7 @@ struct DerivedMesh {
 	struct MLoop *(*getLoopArray)(DerivedMesh * dm);
 	struct MPoly *(*getPolyArray)(DerivedMesh * dm);
 
-	/* copy all verts/edges/faces from the derived mesh into
+	/** Copy all verts/edges/faces from the derived mesh into
 	 * *{vert/edge/face}_r (must point to a buffer large enough)
 	 */
 	void (*copyVertArray)(DerivedMesh *dm, struct MVert *vert_r);
@@ -206,7 +207,7 @@ struct DerivedMesh {
 	void (*copyLoopArray)(DerivedMesh *dm, struct MLoop *loop_r);
 	void (*copyPolyArray)(DerivedMesh *dm, struct MPoly *poly_r);
 
-	/* return a copy of all verts/edges/faces from the derived mesh
+	/** Return a copy of all verts/edges/faces from the derived mesh
 	 * it is the caller's responsibility to free the returned pointer
 	 */
 	struct MVert *(*dupVertArray)(DerivedMesh * dm);
@@ -215,7 +216,7 @@ struct DerivedMesh {
 	struct MLoop *(*dupLoopArray)(DerivedMesh * dm);
 	struct MPoly *(*dupPolyArray)(DerivedMesh * dm);
 
-	/* return a pointer to a single element of vert/edge/face custom data
+	/** Return a pointer to a single element of vert/edge/face custom data
 	 * from the derived mesh (this gives a pointer to the actual data, not
 	 * a copy)
 	 */
@@ -223,7 +224,7 @@ struct DerivedMesh {
 	void *(*getEdgeData)(DerivedMesh * dm, int index, int type);
 	void *(*getTessFaceData)(DerivedMesh * dm, int index, int type);
 
-	/* return a pointer to the entire array of vert/edge/face custom data
+	/** Return a pointer to the entire array of vert/edge/face custom data
 	 * from the derived mesh (this gives a pointer to the actual data, not
 	 * a copy)
 	 */
@@ -231,7 +232,7 @@ struct DerivedMesh {
 	void *(*getEdgeDataArray)(DerivedMesh * dm, int type);
 	void *(*getTessFaceDataArray)(DerivedMesh * dm, int type);
 	
-	/* retrieves the base CustomData structures for 
+	/** Retrieves the base CustomData structures for
 	 * verts/edges/tessfaces/loops/facdes*/
 	CustomData *(*getVertDataLayout)(DerivedMesh * dm);
 	CustomData *(*getEdgeDataLayout)(DerivedMesh * dm);
@@ -239,12 +240,12 @@ struct DerivedMesh {
 	CustomData *(*getLoopDataLayout)(DerivedMesh * dm);
 	CustomData *(*getPolyDataLayout)(DerivedMesh * dm);
 	
-	/*copies all customdata for an element source into dst at index dest*/
+	/** Copies all customdata for an element source into dst at index dest */
 	void (*copyFromVertCData)(DerivedMesh *dm, int source, CustomData *dst, int dest);
 	void (*copyFromEdgeCData)(DerivedMesh *dm, int source, CustomData *dst, int dest);
 	void (*copyFromFaceCData)(DerivedMesh *dm, int source, CustomData *dst, int dest);
 	
-	/* optional grid access for subsurf */
+	/** Optional grid access for subsurf */
 	int (*getNumGrids)(DerivedMesh *dm);
 	int (*getGridSize)(DerivedMesh *dm);
 	struct CCGElem **(*getGridData)(DerivedMesh * dm);
@@ -255,7 +256,7 @@ struct DerivedMesh {
 	unsigned int **(*getGridHidden)(DerivedMesh * dm);
 	
 
-	/* Iterate over each mapped vertex in the derived mesh, calling the
+	/** Iterate over each mapped vertex in the derived mesh, calling the
 	 * given function with the original vert and the mapped vert's new
 	 * coordinate and normal. For historical reasons the normal can be
 	 * passed as a float or short array, only one should be non-NULL.
@@ -265,7 +266,7 @@ struct DerivedMesh {
 	                                       const float no_f[3], const short no_s[3]),
 	                          void *userData);
 
-	/* Iterate over each mapped edge in the derived mesh, calling the
+	/** Iterate over each mapped edge in the derived mesh, calling the
 	 * given function with the original edge and the mapped edge's new
 	 * coordinates.
 	 */
@@ -274,7 +275,7 @@ struct DerivedMesh {
 	                                       const float v0co[3], const float v1co[3]),
 	                          void *userData);
 
-	/* Iterate over each mapped face in the derived mesh, calling the
+	/** Iterate over each mapped face in the derived mesh, calling the
 	 * given function with the original face and the mapped face's (or
 	 * faces') center and normal.
 	 */
@@ -283,51 +284,51 @@ struct DerivedMesh {
 	                                             const float cent[3], const float no[3]),
 	                                void *userData);
 
-	/* Iterate over all vertex points, calling DO_MINMAX with given args.
+	/** Iterate over all vertex points, calling DO_MINMAX with given args.
 	 *
 	 * Also called in Editmode
 	 */
 	void (*getMinMax)(DerivedMesh *dm, float min_r[3], float max_r[3]);
 
-	/* Direct Access Operations */
-	/*  o Can be undefined */
-	/*  o Must be defined for modifiers that only deform however */
+	/** Direct Access Operations
+	 * - Can be undefined
+	 * - Must be defined for modifiers that only deform however */
 
-	/* Get vertex location, undefined if index is not valid */
+	/** Get vertex location, undefined if index is not valid */
 	void (*getVertCo)(DerivedMesh *dm, int index, float co_r[3]);
 
-	/* Fill the array (of length .getNumVerts()) with all vertex locations */
+	/** Fill the array (of length .getNumVerts()) with all vertex locations */
 	void (*getVertCos)(DerivedMesh *dm, float (*cos_r)[3]);
 
-	/* Get smooth vertex normal, undefined if index is not valid */
+	/** Get smooth vertex normal, undefined if index is not valid */
 	void (*getVertNo)(DerivedMesh *dm, int index, float no_r[3]);
 
-	/* Get a map of vertices to faces
+	/** Get a map of vertices to faces
 	 */
 	const struct MeshElemMap *(*getPolyMap)(struct Object *ob, DerivedMesh *dm);
 
-	/* Get the BVH used for paint modes
+	/** Get the BVH used for paint modes
 	 */
 	struct PBVH *(*getPBVH)(struct Object *ob, DerivedMesh *dm);
 
 	/* Drawing Operations */
 
-	/* Draw all vertices as bgl points (no options) */
+	/** Draw all vertices as bgl points (no options) */
 	void (*drawVerts)(DerivedMesh *dm);
 
-	/* Draw edges in the UV mesh (if exists) */
+	/** Draw edges in the UV mesh (if exists) */
 	void (*drawUVEdges)(DerivedMesh *dm);
 
-	/* Draw all edges as lines (no options) 
+	/** Draw all edges as lines (no options)
 	 *
 	 * Also called for *final* editmode DerivedMeshes
 	 */
 	void (*drawEdges)(DerivedMesh *dm, int drawLooseEdges, int drawAllEdges);
 	
-	/* Draw all loose edges (edges w/ no adjoining faces) */
+	/** Draw all loose edges (edges w/ no adjoining faces) */
 	void (*drawLooseEdges)(DerivedMesh *dm);
 
-	/* Draw all faces
+	/** Draw all faces
 	 *  o Set face normal or vertex normal based on inherited face flag
 	 *  o Use inherited face material index to call setMaterial
 	 *  o Only if setMaterial returns true
@@ -337,24 +338,24 @@ struct DerivedMesh {
 	void (*drawFacesSolid)(DerivedMesh *dm, float (*partial_redraw_planes)[4],
 	                       int fast, DMSetMaterial setMaterial);
 
-	/* Draw all faces using MTFace 
-	 *  o Drawing options too complicated to enumerate, look at code.
+	/** Draw all faces using MTFace
+	 * - Drawing options too complicated to enumerate, look at code.
 	 */
 	void (*drawFacesTex)(DerivedMesh *dm,
 	                     DMSetDrawOptionsTex setDrawOptions,
 	                     DMCompareDrawOptions compareDrawOptions,
 	                     void *userData);
 
-	/* Draw all faces with GLSL materials
+	/** Draw all faces with GLSL materials
 	 *  o setMaterial is called for every different material nr
 	 *  o Only if setMaterial returns true
 	 */
 	void (*drawFacesGLSL)(DerivedMesh *dm, DMSetMaterial setMaterial);
 
-	/* Draw mapped faces (no color, or texture)
-	 *  o Only if !setDrawOptions or
-	 *    setDrawOptions(userData, mapped-face-index, drawSmooth_r)
-	 *    returns true
+	/** Draw mapped faces (no color, or texture)
+	 * - Only if !setDrawOptions or
+	 *   setDrawOptions(userData, mapped-face-index, drawSmooth_r)
+	 *   returns true
 	 *
 	 * If drawSmooth is set to true then vertex normals should be set and
 	 * glShadeModel called with GL_SMOOTH. Otherwise the face normal should
@@ -371,36 +372,36 @@ struct DerivedMesh {
 	                        void *userData,
 	                        DMDrawFlag flag);
 
-	/* Draw mapped faces using MTFace 
-	 *  o Drawing options too complicated to enumerate, look at code.
+	/** Draw mapped faces using MTFace
+	 * - Drawing options too complicated to enumerate, look at code.
 	 */
 	void (*drawMappedFacesTex)(DerivedMesh *dm,
 	                           DMSetDrawOptions setDrawOptions,
 	                           DMCompareDrawOptions compareDrawOptions,
 	                           void *userData);
 
-	/* Draw mapped faces with GLSL materials
-	 *  o setMaterial is called for every different material nr
-	 *  o setDrawOptions is called for every face
-	 *  o Only if setMaterial and setDrawOptions return true
+	/** Draw mapped faces with GLSL materials
+	 * - setMaterial is called for every different material nr
+	 * - setDrawOptions is called for every face
+	 * - Only if setMaterial and setDrawOptions return true
 	 */
 	void (*drawMappedFacesGLSL)(DerivedMesh *dm,
 	                            DMSetMaterial setMaterial,
 	                            DMSetDrawOptions setDrawOptions,
 	                            void *userData);
 
-	/* Draw mapped edges as lines
-	 *  o Only if !setDrawOptions or setDrawOptions(userData, mapped-edge)
-	 *    returns true
+	/** Draw mapped edges as lines
+	 * - Only if !setDrawOptions or setDrawOptions(userData, mapped-edge)
+	 *   returns true
 	 */
 	void (*drawMappedEdges)(DerivedMesh *dm,
 	                        DMSetDrawOptions setDrawOptions,
 	                        void *userData);
 
-	/* Draw mapped edges as lines with interpolation values
-	 *  o Only if !setDrawOptions or
-	 *    setDrawOptions(userData, mapped-edge, mapped-v0, mapped-v1, t)
-	 *    returns true
+	/** Draw mapped edges as lines with interpolation values
+	 * - Only if !setDrawOptions or
+	 *   setDrawOptions(userData, mapped-edge, mapped-v0, mapped-v1, t)
+	 *   returns true
 	 *
 	 * NOTE: This routine is optional!
 	 */
@@ -409,32 +410,32 @@ struct DerivedMesh {
 	                              DMSetDrawInterpOptions setDrawInterpOptions,
 	                              void *userData);
 
-	/* Draw all faces with materials
-	 *  o setMaterial is called for every different material nr
-	 *  o setFace is called to verify if a face must be hidden
+	/** Draw all faces with materials
+	 * - setMaterial is called for every different material nr
+	 * - setFace is called to verify if a face must be hidden
 	 */
 	void (*drawMappedFacesMat)(DerivedMesh *dm,
 	                           void (*setMaterial)(void *userData, int, void *attribs),
 	                           int (*setFace)(void *userData, int index), void *userData);
 
-	/* Release reference to the DerivedMesh. This function decides internally
+	/** Release reference to the DerivedMesh. This function decides internally
 	 * if the DerivedMesh will be freed, or cached for later use. */
 	void (*release)(DerivedMesh *dm);
 };
 
-/* utility function to initialize a DerivedMesh's function pointers to
+/** utility function to initialize a DerivedMesh's function pointers to
  * the default implementation (for those functions which have a default)
  */
 void DM_init_funcs(DerivedMesh *dm);
 
-/* utility function to initialize a DerivedMesh for the desired number
+/** utility function to initialize a DerivedMesh for the desired number
  * of vertices, edges and faces (doesn't allocate memory for them, just
  * sets up the custom data layers)
  */
 void DM_init(DerivedMesh *dm, DerivedMeshType type, int numVerts, int numEdges, 
              int numFaces, int numLoops, int numPolys);
 
-/* utility function to initialize a DerivedMesh for the desired number
+/** utility function to initialize a DerivedMesh for the desired number
  * of vertices, edges and faces, with a layer setup copied from source
  */
 void DM_from_template(DerivedMesh *dm, DerivedMesh *source,
@@ -442,12 +443,12 @@ void DM_from_template(DerivedMesh *dm, DerivedMesh *source,
                       int numVerts, int numEdges, int numFaces,
                       int numLoops, int numPolys);
 
-/* utility function to release a DerivedMesh's layers
+/** utility function to release a DerivedMesh's layers
  * returns 1 if DerivedMesh has to be released by the backend, 0 otherwise
  */
 int DM_release(DerivedMesh *dm);
 
-/* utility function to convert a DerivedMesh to a Mesh
+/** utility function to convert a DerivedMesh to a Mesh
  */
 void DM_to_mesh(DerivedMesh *dm, struct Mesh *me, struct Object *ob);
 
@@ -459,11 +460,10 @@ void          DM_to_bmesh_ex(struct DerivedMesh *dm, struct BMesh *bm);
 struct BMesh *DM_to_bmesh(struct DerivedMesh *dm);
 
 
-/* utility function to convert a DerivedMesh to a shape key block 
- */
+/** Utility function to convert a DerivedMesh to a shape key block */
 void DM_to_meshkey(DerivedMesh *dm, struct Mesh *me, struct KeyBlock *kb);
 
-/* set the CD_FLAG_NOCOPY flag in custom data layers where the mask is
+/** set the CD_FLAG_NOCOPY flag in custom data layers where the mask is
  * zero for the layer type, so only layer types specified by the mask
  * will be copied
  */
@@ -545,7 +545,7 @@ void DM_ensure_tessface(DerivedMesh *dm);
 
 void DM_update_tessface_data(DerivedMesh *dm);
 
-/* interpolates vertex data from the vertices indexed by src_indices in the
+/** interpolates vertex data from the vertices indexed by src_indices in the
  * source mesh using the given weights and stores the result in the vertex
  * indexed by dest_index in the dest mesh
  */
@@ -553,7 +553,7 @@ void DM_interp_vert_data(struct DerivedMesh *source, struct DerivedMesh *dest,
                          int *src_indices, float *weights,
                          int count, int dest_index);
 
-/* interpolates edge data from the edges indexed by src_indices in the
+/** interpolates edge data from the edges indexed by src_indices in the
  * source mesh using the given weights and stores the result in the edge indexed
  * by dest_index in the dest mesh.
  * if weights is NULL, all weights default to 1.
@@ -566,7 +566,7 @@ void DM_interp_edge_data(struct DerivedMesh *source, struct DerivedMesh *dest,
                          float *weights, EdgeVertWeight *vert_weights,
                          int count, int dest_index);
 
-/* interpolates face data from the faces indexed by src_indices in the
+/** interpolates face data from the faces indexed by src_indices in the
  * source mesh using the given weights and stores the result in the face indexed
  * by dest_index in the dest mesh.
  * if weights is NULL, all weights default to 1.
@@ -592,7 +592,7 @@ void DM_interp_poly_data(struct DerivedMesh *source, struct DerivedMesh *dest,
 /* Temporary? A function to give a colorband to derivedmesh for vertexcolor ranges */
 void vDM_ColorBand_store(struct ColorBand *coba);
 
-/* Simple function to get me->totvert amount of vertices/normals,
+/** Simple function to get me->totvert amount of vertices/normals,
  * correctly deformed and subsurfered. Needed especially when vertexgroups are involved.
  * In use now by vertex/weight paint and particles */
 float *mesh_get_mapped_verts_nors(struct Scene *scene, struct Object *ob);
@@ -641,13 +641,13 @@ int editbmesh_modifier_is_enabled(struct Scene *scene, struct ModifierData *md,
 void makeDerivedMesh(struct Scene *scene, struct Object *ob, struct BMEditMesh *em, 
                      CustomDataMask dataMask, int build_shapekey_layers);
 
-/* returns an array of deform matrices for crazyspace correction, and the
+/** returns an array of deform matrices for crazyspace correction, and the
  * number of modifiers left */
 int editbmesh_get_first_deform_matrices(struct Scene *, struct Object *, struct BMEditMesh *em,
                                         float (**deformmats)[3][3], float (**deformcos)[3]);
 
 void weight_to_rgb(float r_rgb[3], const float weight);
-/* Update the weight MCOL preview layer.
+/** Update the weight MCOL preview layer.
  * If weights are NULL, use object's active vgroup(s).
  * Else, weights must be an array of weight float values.
  *     If indices is NULL, it must be of numVerts length.
@@ -657,7 +657,7 @@ void weight_to_rgb(float r_rgb[3], const float weight);
 void DM_update_weight_mcol(struct Object *ob, struct DerivedMesh *dm, int const draw_flag,
                            float *weights, int num, const int *indices);
 
-/* convert layers requested by a GLSL material to actually available layers in
+/** convert layers requested by a GLSL material to actually available layers in
  * the DerivedMesh, with both a pointer for arrays and an offset for editmesh */
 typedef struct DMVertexAttribs {
 	struct {
@@ -689,7 +689,7 @@ void DM_vertex_attributes_from_gpu(DerivedMesh *dm,
 void DM_add_tangent_layer(DerivedMesh *dm);
 void DM_calc_auto_bump_scale(DerivedMesh *dm);
 
-/* Set object's bounding box based on DerivedMesh min/max data */
+/** Set object's bounding box based on DerivedMesh min/max data */
 void DM_set_object_boundbox(struct Object *ob, DerivedMesh *dm);
 
 void DM_init_origspace(DerivedMesh *dm);