doxygen: corrections/updates

Also add depsgraph & physics

doc/doxygen/doxygen.intern.h

@@ -10,26 +10,14 @@
  *  \ingroup intern
  */
 
-/** \defgroup boolop boolop
- *  \ingroup intern
- */
-
 /** \defgroup ctr container
  *  \ingroup intern
  */
 
-/** \defgroup decimation decimation
- *  \ingroup intern
- */
-
 /** \defgroup elbeem elbeem
  *  \ingroup intern
  */
 
-/** \defgroup bsp bsp
- *  \ingroup intern
- */
-
 /** \defgroup iksolver iksolver
  *  \ingroup intern
  */

doc/doxygen/doxygen.source.h

@@ -93,36 +93,44 @@
 
 /* ================================ */
 
-/** \defgroup blender blender */
+/** \defgroup blender Blender */
 
-/** \defgroup blf blenfont
+/** \defgroup blf BlenFont
  *  \ingroup blender
  */
 
-/** \defgroup bke blenkernel
+/** \defgroup bke BlenKernel
  *  \ingroup blender
  */
 
-/** \defgroup bli blenlib
+/** \defgroup bli BlenLib
  *  \ingroup blender
  */
 
-/** \defgroup nodes nodes
+/** \defgroup depsgraph Dependency Graph
  *  \ingroup blender
  */
 
-/** \defgroup cmpnodes cmpnodes
+/** \defgroup bph Physics
+ *  \ingroup blender
+ */
+
+/** \defgroup nodes Nodes
+ *  \ingroup blender
+ */
+
+/** \defgroup cmpnodes Nodes (Compositor)
  *  \ingroup nodes
  */
 
-/** \defgroup shdnodes shdnodes
+/** \defgroup shdnodes Nodes (Shader)
  *  \ingroup nodes
  */
 
-/** \defgroup texnodes texnodes
+/** \defgroup texnodes Nodes (Texture)
  *  \ingroup nodes
  */
-/** \defgroup modifiers modifiers
+/** \defgroup modifiers Object Modifiers
  *  \ingroup blender
  */
 
@@ -132,29 +140,29 @@
  *  \ingroup blender
  */
 
-/** \defgroup ikplugin ikplugin
+/** \defgroup ikplugin IK Plugin
  *  \ingroup blender
  */
 
-/** \defgroup DNA sDNA
+/** \defgroup DNA Struct DNA (File Format)
  *  \ingroup blender data
  */
-/** \defgroup RNA RNA
+/** \defgroup RNA RNA (Data API)
  *  \ingroup blender data
  */
 
-/** \defgroup blenloader .blend read and write functions
+/** \defgroup blenloader Blend file IO
  *  \ingroup blender data
  *  \todo check if \ref blo and \ref blenloader groups can be
  *   merged in docs.
  */
 
-/** \defgroup quicktime quicktime
+/** \defgroup quicktime QuickTime
  *  \ingroup blender
 
 /** \defgroup gui GUI */
 
-/** \defgroup wm windowmanager
+/** \defgroup wm Window Manager
  *  \ingroup blender gui
  */
 
@@ -324,7 +332,7 @@
  *  \ingroup externformats
  */
 
-/** \defgroup imbuf IMage Buffer
+/** \defgroup imbuf Image Buffer (ImBuf)
  *  \ingroup blender
  */
 

extern/bullet2/src/BulletCollision/CollisionDispatch/btCollisionWorld.h

@@ -15,7 +15,7 @@ subject to the following restrictions:
 
 
 /**
- * @mainpage Bullet Documentation
+ * @page Bullet Documentation
  *
  * @section intro_sec Introduction
  * Bullet is a Collision Detection and Rigid Body Dynamics Library. The Library is Open Source and free for commercial use, under the ZLib license ( http://opensource.org/licenses/zlib-license.php ).

intern/ghost/intern/GHOST_SystemX11.h

@@ -156,10 +156,6 @@ public:
 	    const GHOST_TEmbedderWindowID parentWindow = 0
 	    );
 
-	/**
-	 * \section Interface Inherited from GHOST_ISystem
-	 */
-
 	/**
 	 * Retrieves events from the system and stores them in the queue.
 	 * \param waitForEvent Flag to wait for an event (or return immediately).
@@ -170,9 +166,6 @@ public:
 	    bool waitForEvent
 	    );
 
-	/**
-	 * \section Interface Inherited from GHOST_System
-	 */
 	GHOST_TSuccess
 	getCursorPosition(
 	    GHOST_TInt32& x,
@@ -206,7 +199,6 @@ public:
 	    ) const;
 
 	/**
-	 * \section Interface Dirty
 	 * Flag a window as dirty. This will
 	 * generate a GHOST window update event on a call to processEvents() 
 	 */

intern/iksolver/extern/IK_solver.h

@@ -35,10 +35,10 @@
 
  * Copyright (C) 2001 NaN Technologies B.V.
  *
- * @author Laurence, Brecht
- * @mainpage IK - Blender inverse kinematics module.
+ * \author Laurence, Brecht
+ * \page IK - Blender inverse kinematics module.
  *
- * @section about About the IK module
+ * \section about About the IK module
  *
  * This module allows you to create segments and form them into 
  * tree. You can then define a goal points that the end of a given 
@@ -47,7 +47,7 @@
  * to get the as near as possible to the goal. This solver uses an
  * inverse jacobian method to find a solution.
  * 
- * @section issues Known issues with this IK solver.
+ * \section issues Known issues with this IK solver.
  *
  * - There is currently no support for joint constraints in the
  * solver. This is within the realms of possibility - please ask
@@ -60,7 +60,7 @@
  * Other algorithms exist which are more suitable for real-time
  * applications, please ask if this functionality is required.     
  * 
- * @section dependencies Dependencies
+ * \section dependencies Dependencies
  * 
  * This module only depends on Moto.
  */

intern/memutil/MEM_CacheLimiter.h

@@ -29,20 +29,22 @@
 #define __MEM_CACHELIMITER_H__
 
 /**
- * @section MEM_CacheLimiter
+ * \section MEM_CacheLimiter
  * This class defines a generic memory cache management system
  * to limit memory usage to a fixed global maximum.
  *
- * Please use the C-API in MEM_CacheLimiterC-Api.h for code written in C.
+ * \note Please use the C-API in MEM_CacheLimiterC-Api.h for code written in C.
  *
  * Usage example:
  *
+ * \code{.cpp}
  * class BigFatImage {
  * public:
  *       ~BigFatImage() { tell_everyone_we_are_gone(this); }
  * };
  *
- * void doit() {
+ * void doit()
+ * {
  *     MEM_Cache<BigFatImage> BigFatImages;
  *
  *     MEM_Cache_Handle<BigFatImage>* h = BigFatImages.insert(new BigFatImage);
@@ -50,11 +52,12 @@
  *     BigFatImages.enforce_limits();
  *     h->ref();
  *
- *     work with image...
+ *     // work with image...
  *
  *     h->unref();
  *
- *     leave image in cache.
+ *     // leave image in cache.
+ * \endcode
  */
 
 #include <list>

intern/memutil/MEM_RefCountPtr.h

@@ -30,9 +30,9 @@
  */
 
 /**
- * @file	MEM_RefCountPtr.h
+ * \file	MEM_RefCountPtr.h
  * Declaration of MEM_RefCounted and MEM_RefCountable classes.
- * @author Laurence
+ * \author Laurence
  */
 
 #ifndef __MEM_REFCOUNTPTR_H__
@@ -41,7 +41,7 @@
 #include <stdlib.h> // for NULL !
 
 /**
- * @section MEM_RefCountable
+ * \section MEM_RefCountable
  * This is a base class for reference countable objects.
  * If you want an object to be shared using a reference 
  * counted system derrivce from this class. All subclasses
@@ -50,9 +50,9 @@
  * defining a static New() method that returns a ref counted
  * ptr to a new()ly allocated instance. 
  *
- * @section Example subclass
- *
+ * \section Example subclass
  *
+ * \code{.cpp}
  * class MySharedObject : public MEM_RefCountable {
  *
  * private :
@@ -68,6 +68,7 @@
  *		
  *		// other member functions
  * };
+ * \endcode
  *
  * Alternitively you may first wish to define a fully functional
  * class and then define a reference counting wrapper for this class.
@@ -75,6 +76,8 @@
  * counting.
  *
  * E.g.
+ *
+ * \code{.cpp}
  * class UsefullClass {
  * private :
  *  ...
@@ -108,7 +111,7 @@
  *  // mechanism to handle object lifetime.
  *  ~RcUsefullClass();
  * };
- *
+ * \endcode
  *
  */
 
@@ -168,7 +171,7 @@ public :
 };
 
 /**
- * @section MEM_RefCountPtr
+ * \section MEM_RefCountPtr
  */
 
 template

intern/memutil/MEM_SmartPtr.h

@@ -43,7 +43,7 @@
 
 
 /**
- * @section MEM_SmartPtr 
+ * \section MEM_SmartPtr
  * This class defines a smart pointer similar to that defined in 
  * the Standard Template Library but without the painful get()
  * semantics to access the internal c style pointer.
@@ -58,8 +58,9 @@
  * should not be shared. This is not reliably enforceable in C++
  * but this class attempts to make the 1-1 relationship clear.
  * 
- * @section Example usage
+ * \section Example usage
  *
+ * \code{.cpp}
  * class foo {
  *		...constructors accessors etc.
  *		int x[1000];
@@ -86,18 +87,21 @@
  *	private :
  *		MEM_SmartPtr<foo> m_foo;
  *	}
+ * \endcode
  *
  * You may also safely construct vectors of MEM_SmartPtrs and 
  * have the vector own stuff you put into it. 
  *
  * e.g.
+ * \code{.cpp}
  * { 
- * std::vector<MEM_SmartPtr<foo> > foo_vector;
- * foo_vector.push_back( new foo());
- * foo_vector.push_back( new foo());
+ *     std::vector<MEM_SmartPtr<foo> > foo_vector;
+ *     foo_vector.push_back( new foo());
+ *     foo_vector.push_back( new foo());
  *
- * foo_vector[0]->bla();
+ *     foo_vector[0]->bla();
  * } // foo_vector out of scope => heap memory freed for both foos
+ * \endcode
  *
  * @warning this class should only be used for objects created
  * on the heap via the new function. It will not behave correctly

source/blender/avi/AVI_avi.h

@@ -28,18 +28,17 @@
 
 /** \file AVI_avi.h
  *  \ingroup avi
- * \section aviabout AVI module external interface
  *
- * \subsection about About the AVI module
+ * \section avi_about About the AVI module
  *
  * This is external code. It provides avi file import/export and
  * conversions. It has been adapted to make use of Blender memory
  * management functions, and because of this it needs module
  * blenlib. You need to provide this lib when linking with libavi.a .
  *
- * \subsection issues Known issues with AVI
+ * \subsection avi_issues Known issues with AVI
  *
- * - avi uses mallocN, freeN from blenlib. 
+ * - avi uses #MEM_mallocN, #MEM_freeN from blenlib.
  * - Not all functions that are used externally are properly
  *   prototyped.
  *

source/blender/blenkernel/BKE_mesh.h

@@ -276,7 +276,7 @@ int BKE_mesh_recalc_tessellation(
         struct CustomData *fdata, struct CustomData *ldata, struct CustomData *pdata,
         struct MVert *mvert,
         int totface, int totloop, int totpoly,
-        const bool do_face_normals);
+        const bool do_face_nor_copy);
 int BKE_mesh_mpoly_to_mface(
         struct CustomData *fdata, struct CustomData *ldata,
         struct CustomData *pdata, int totface, int totloop, int totpoly);

source/blender/blenkernel/intern/dynamicpaint.c

@@ -2964,15 +2964,16 @@ static void mesh_faces_nearest_point_dp(void *userdata, int index, const float c
 /**
  * Mix color values to canvas point.
  *
- * \param surface canvas surface
- * \param index surface point index
- * \param paintFlags paint object flags
- * \param paintColor,Alpha,Wetness to be mixed paint values
- * \param timescale value used to adjust time dependent
+ * \param surface: Canvas surface
+ * \param index: Surface point index
+ * \param paintFlags: paint object flags
+ * \param paintColor,paintAlpha,paintWetness: To be mixed paint values
+ * \param timescale: Value used to adjust time dependent
  * operations when using substeps
  */
-static void dynamicPaint_mixPaintColors(DynamicPaintSurface *surface, int index, int paintFlags,
-                                        const float paintColor[3], float *paintAlpha, float *paintWetness, float *timescale)
+static void dynamicPaint_mixPaintColors(
+        DynamicPaintSurface *surface, int index, int paintFlags,
+        const float paintColor[3], float *paintAlpha, float *paintWetness, float *timescale)
 {
 	PaintPoint *pPoint = &((PaintPoint *)surface->data->type_data)[index];
 

source/blender/blenkernel/intern/mesh_evaluate.c

@@ -2253,12 +2253,15 @@ void BKE_mesh_loops_to_tessdata(CustomData *fdata, CustomData *ldata, CustomData
 /**
  * Recreate tessellation.
  *
- * \param do_face_nor_copy controls whether the normals from the poly are copied to the tessellated faces.
+ * \param do_face_nor_copy: Controls whether the normals from the poly are copied to the tessellated faces.
  *
  * \return number of tessellation faces.
  */
-int BKE_mesh_recalc_tessellation(CustomData *fdata, CustomData *ldata, CustomData *pdata,
-                                 MVert *mvert, int totface, int totloop, int totpoly, const bool do_face_nor_cpy)
+int BKE_mesh_recalc_tessellation(
+        CustomData *fdata, CustomData *ldata, CustomData *pdata,
+        MVert *mvert,
+        int totface, int totloop, int totpoly,
+        const bool do_face_nor_copy)
 {
 	/* use this to avoid locking pthread for _every_ polygon
 	 * and calling the fill function */
@@ -2468,7 +2471,7 @@ int BKE_mesh_recalc_tessellation(CustomData *fdata, CustomData *ldata, CustomDat
 	CustomData_add_layer(fdata, CD_ORIGINDEX, CD_ASSIGN, mface_to_poly_map, totface);
 	CustomData_from_bmeshpoly(fdata, pdata, ldata, totface);
 
-	if (do_face_nor_cpy) {
+	if (do_face_nor_copy) {
 		/* If polys have a normals layer, copying that to faces can help
 		 * avoid the need to recalculate normals later */
 		if (CustomData_has_layer(pdata, CD_NORMAL)) {

source/blender/blenkernel/intern/object_deform.c

@@ -163,7 +163,7 @@ MDeformVert *BKE_object_defgroup_data_create(ID *id)
 /**
  * Remove all verts (or only selected ones) from given vgroup. Work in Object and Edit modes.
  *
- * \param allverts If true, remove all vertices, else only selected ones.
+ * \param use_selection: Only operate on selection.
  * \return True if any vertex was removed, false otherwise.
  */
 bool BKE_object_defgroup_clear(Object *ob, bDeformGroup *dg, const bool use_selection)
@@ -241,7 +241,7 @@ bool BKE_object_defgroup_clear(Object *ob, bDeformGroup *dg, const bool use_sele
 /**
  * Remove all verts (or only selected ones) from all vgroups. Work in Object and Edit modes.
  *
- * \param allverts If true, remove all vertices, else only selected ones.
+ * \param use_selection: Only operate on selection.
  * \return True if any vertex was removed, false otherwise.
  */
 bool BKE_object_defgroup_clear_all(Object *ob, const bool use_selection)

source/blender/blenlib/intern/BLI_dynstr.c

@@ -258,11 +258,11 @@ int BLI_dynstr_get_len(DynStr *ds)
 
 /**
  * Get a DynStr's contents as a c-string.
- * <i> The str argument must be allocated to be at
- * least the size of BLI_dynstr_get_len(ds) + 1. </i>
+ * he \a rets argument must be allocated to be at
+ * least the size of ``BLI_dynstr_get_len(ds) + 1``.
  *
- * \param ds The DynStr of interest.
- * \param str The string to fill.
+ * \param ds: The DynStr of interest.
+ * \param rets: The string to fill.
  */
 void BLI_dynstr_get_cstring_ex(DynStr *__restrict ds, char *__restrict rets)
 {

source/blender/blenlib/intern/convexhull2d.c

@@ -239,7 +239,7 @@ int BLI_convexhull_2d(const float (*points)[2], const int n, int r_points[])
  *
  * Intended to be used with #BLI_convexhull_2d
  *
- * \param points  Ordered hull points
+ * \param points_hull  Ordered hull points
  * (result of #BLI_convexhull_2d mapped to a contiguous array).
  *
  * \note we could return the index of the best edge too if its needed.

source/blender/blenlib/intern/edgehash.c

@@ -454,9 +454,9 @@ void *BLI_edgehash_lookup_default(EdgeHash *eh, unsigned int v0, unsigned int v1
 }
 
 /**
- * Remove \a key from \a eh, or return false if the key wasn't found.
+ * Remove \a key (v0, v1) from \a eh, or return false if the key wasn't found.
  *
- * \param key  The key to remove.
+ * \param v0, v1: The key to remove.
  * \param valfreefp  Optional callback to free the value.
  * \return true if \a key was removed from \a eh.
  */
@@ -480,9 +480,9 @@ bool BLI_edgehash_remove(EdgeHash *eh, unsigned int v0, unsigned int v1, EdgeHas
 /* same as above but return the value,
  * no free value argument since it will be returned */
 /**
- * Remove \a key from \a eh, returning the value or NULL if the key wasn't found.
+ * Remove \a key (v0, v1) from \a eh, returning the value or NULL if the key wasn't found.
  *
- * \param key  The key to remove.
+ * \param v0, v1: The key to remove.
  * \return the value of \a key int \a eh or NULL.
  */
 void *BLI_edgehash_popkey(EdgeHash *eh, unsigned int v0, unsigned int v1)

source/blender/blenlib/intern/gsqueue.c

@@ -96,8 +96,8 @@ int BLI_gsqueue_size(GSQueue *gq)
  * Access the item at the head of the queue
  * without removing it.
  *
- * \param item_r A pointer to an appropriately
- * sized structure (the size passed to BLI_gsqueue_new)
+ * \param r_item: A pointer to an appropriately
+ * sized structure (the size passed to #BLI_gsqueue_new)
  */
 void BLI_gsqueue_peek(GSQueue *gq, void *r_item)
 {
@@ -108,8 +108,8 @@ void BLI_gsqueue_peek(GSQueue *gq, void *r_item)
  * Access the item at the head of the queue
  * and remove it.
  *
- * \param item_r A pointer to an appropriately
- * sized structure (the size passed to BLI_gsqueue_new).
+ * \param r_item: A pointer to an appropriately
+ * sized structure (the size passed to #BLI_gsqueue_new).
  * Can be NULL if desired.
  */
 void BLI_gsqueue_pop(GSQueue *gq, void *r_item)

source/blender/blenlib/intern/string_utf8.c

@@ -329,8 +329,8 @@ size_t BLI_strnlen_utf8_ex(const char *strc, const size_t maxlen, size_t *r_len_
 }
 
 /**
- * \param start the string to measure the length.
- * \param maxlen the string length (in bytes)
+ * \param strc: the string to measure the length.
+ * \param maxlen: the string length (in bytes)
  * \return the unicode length (not in bytes!)
  */
 size_t BLI_strnlen_utf8(const char *strc, const size_t maxlen)
@@ -599,14 +599,14 @@ unsigned int BLI_str_utf8_as_unicode_step(const char *__restrict p, size_t *__re
 /* was g_unichar_to_utf8 */
 /**
  * BLI_str_utf8_from_unicode:
- * @c a Unicode character code
- * \param outbuf output buffer, must have at least 6 bytes of space.
+ * \param c: a Unicode character code
+ * \param outbuf: output buffer, must have at least 6 bytes of space.
  *       If %NULL, the length will be computed and returned
  *       and nothing will be written to outbuf.
  *
  * Converts a single character to UTF-8.
  *
- * Return value: number of bytes written
+ * \return number of bytes written
  **/
 size_t BLI_str_utf8_from_unicode(unsigned int c, char *outbuf)
 {

source/blender/blenlib/intern/timecode.c

@@ -196,7 +196,6 @@ size_t BLI_timecode_string_from_time(
  * \param power  special setting for #View2D grid drawing,
  *        used to specify how detailed we need to be
  * \param time_seconds  time total time in seconds
- * \param seconds  time in seconds.
  * \return length of \a str
  *
  * \note in some cases this is used to print non-seconds values.

source/blender/blenloader/BLO_readfile.h

@@ -119,8 +119,8 @@ BLO_blendfiledata_free(BlendFileData *bfd);
 /**
  * Open a blendhandle from a file path.
  *
- * \param file The file path to open.
- * \param reports Report errors in opening the file (can be NULL).
+ * \param filepath: The file path to open.
+ * \param reports: Report errors in opening the file (can be NULL).
  * \return A handle on success, or NULL on failure.
  */
 BlendHandle *BLO_blendhandle_from_file(

source/blender/blenloader/intern/writefile.c

@@ -407,7 +407,7 @@ static void mywrite(WriteData *wd, const void *adr, int len)
 
 /**
  * BeGiN initializer for mywrite
- * \param file File descriptor
+ * \param ww: File write wrapper.
  * \param compare Previous memory file (can be NULL).
  * \param current The current memory file (can be NULL).
  * \warning Talks to other functions with global parameters

source/blender/bmesh/intern/bmesh_core.c

@@ -2193,7 +2193,7 @@ void bmesh_vert_separate(
  *
  * Any edges which failed to split off in #bmesh_vert_separate will be merged back into the original edge.
  *
- * \param edges_seperate
+ * \param edges_separate
  * A list-of-lists, each list is from a single original edge (the first edge is the original),
  * Check for duplicates (not just with the first) but between all.
  * This is O(n2) but radial edges are very rarely >2 and almost never >~10.

source/blender/bmesh/intern/bmesh_mods.c

@@ -270,7 +270,7 @@ BMFace *BM_faces_join_pair(BMesh *bm, BMFace *f_a, BMFace *f_b, BMEdge *e, const
  * the split edge to be created (must be differ and not can't be adjacent in the face).
  * \param r_l pointer which will receive the BMLoop for the split edge in the new face
  * \param example Edge used for attributes of splitting edge, if non-NULL
- * \param nodouble Use an existing edge if found
+ * \param no_double: Use an existing edge if found
  *
  * \return Pointer to the newly created face representing one side of the split
  * if the split is successful (and the original original face will be the

source/blender/bmesh/tools/bmesh_decimate_collapse.c

@@ -444,7 +444,7 @@ static void bm_decim_triangulate_end(BMesh *bm)
 #ifdef USE_CUSTOMDATA
 
 /**
- * \param v is the target to merge into.
+ * \param l: defines the vert to collapse into.
  */
 static void bm_edge_collapse_loop_customdata(
         BMesh *bm, BMLoop *l, BMVert *v_clear, BMVert *v_other,
@@ -457,8 +457,6 @@ static void bm_edge_collapse_loop_customdata(
 	const bool is_manifold = BM_edge_is_manifold(l->e);
 	int side;
 
-	/* l defines the vert to collapse into  */
-
 	/* first find the loop of 'v_other' thats attached to the face of 'l' */
 	if (l->v == v_clear) {
 		l_clear = l;
@@ -700,8 +698,8 @@ static bool bm_edge_collapse_is_degenerate_topology(BMEdge *e_first)
  *
  * Important - dont add vert/edge/face data on collapsing!
  *
- * \param e_clear_other let caller know what edges we remove besides \a e_clear
- * \param customdata_flag merge factor, scales from 0 - 1 ('v_clear' -> 'v_other')
+ * \param r_e_clear_other: Let caller know what edges we remove besides \a e_clear
+ * \param customdata_flag: Merge factor, scales from 0 - 1 ('v_clear' -> 'v_other')
  */
 static bool bm_edge_collapse(
         BMesh *bm, BMEdge *e_clear, BMVert *v_clear, int r_e_clear_other[2],

source/blender/bmesh/tools/bmesh_edgenet.c

@@ -448,7 +448,6 @@ static LinkNode *bm_edgenet_path_calc_best(
  *
  * \param bm  The mesh to operate on.
  * \param use_edge_tag  Only fill tagged edges.
- * \param face_oflag  if nonzero, apply all new faces with this bmo flag.
  */
 void BM_mesh_edgenet(
         BMesh *bm,

source/blender/bmesh/tools/bmesh_edgesplit.c

@@ -37,7 +37,6 @@
 
 /**
  * \param use_verts  Use flagged verts instead of edges.
- * \param use_non_manifold  Split non-manifold edges (a little slower, must check for doubles).
  * \param tag_only  Only split tagged edges.
  * \param copy_select  Copy selection history.
  */

source/blender/bmesh/tools/bmesh_wireframe.c

@@ -160,7 +160,7 @@ static bool bm_loop_is_radial_boundary(BMLoop *l_first)
 }
 
 /**
- * \param def_nr  -1 for no vertex groups.
+ * \param defgrp_index: Vertex group index, -1 for no vertex groups.
  *
  * \note All edge tags must be cleared.
  * \note Behavior matches MOD_solidify.c

source/blender/compositor/COM_compositor.h

@@ -38,7 +38,7 @@ extern "C" {
  * @defgroup Node All nodes of the compositor
  * @defgroup Operation All operations of the compositor
  *
- * @mainpage Introduction of the Blender Compositor
+ * @page Introduction of the Blender Compositor
  *
  * @section bcomp Blender compositor
  * This project redesigns the internals of Blender's compositor. The project has been executed in 2011 by At Mind.

source/blender/depsgraph/DEG_depsgraph.h

@@ -22,14 +22,15 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
- *
- * Public API for Depsgraph
  */
 
-#ifndef __DEG_DEPSGRAPH_H__
-#define __DEG_DEPSGRAPH_H__
-
-/* Dependency Graph
+/** \file blender/depsgraph/DEG_depsgraph.h
+ *  \ingroup depsgraph
+ *
+ * Public API for Depsgraph
+ *
+ * Dependency Graph
+ * ================
  *
  * The dependency graph tracks relations between various pieces of data in
  * a Blender file, but mainly just those which make up scene data. It is used
@@ -39,6 +40,7 @@
  *
  *
  * Evaluation Engine
+ * =================
  *
  * The evaluation takes the operation-nodes the Depsgraph has tagged for updating, 
  * and schedules them up for being evaluated/executed such that the all dependency
@@ -50,6 +52,9 @@
  * - These are used in all depsgraph code and by all callers of Depsgraph API...
  */
 
+#ifndef __DEG_DEPSGRAPH_H__
+#define __DEG_DEPSGRAPH_H__
+
 /* Dependency Graph */
 typedef struct Depsgraph Depsgraph;
 

source/blender/depsgraph/DEG_depsgraph_build.h

@@ -22,6 +22,10 @@
  * Contributor(s): Lukas Toenne
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/DEG_depsgraph_build.h
+ *  \ingroup depsgraph
  *
  * Public API for Depsgraph
  */

source/blender/depsgraph/DEG_depsgraph_debug.h

@@ -22,6 +22,10 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/DEG_depsgraph_debug.h
+ *  \ingroup depsgraph
  *
  * Public API for Querying and Filtering Depsgraph
  */

source/blender/depsgraph/DEG_depsgraph_query.h

@@ -22,8 +22,12 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/DEG_depsgraph_query.h
+ *  \ingroup depsgraph
  *
- * Public API for Querying and Filtering Depsgraph
+ * Public API for Querying and Filtering Depsgraph.
  */
 
 #ifndef __DEG_DEPSGRAPH_QUERY_H__

source/blender/depsgraph/intern/depsgraph.cc

@@ -22,8 +22,12 @@
  * Contributor(s): Sergey Sharybin
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph.cc
+ *  \ingroup depsgraph
  *
- * Core routines for how the Depsgraph works
+ * Core routines for how the Depsgraph works.
  */
 
 #include <string.h>

source/blender/depsgraph/intern/depsgraph.h

@@ -22,6 +22,10 @@
  * Contributor(s): Sergey Sharybin
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph.h
+ *  \ingroup depsgraph
  *
  * Datatypes for internal use in the Depsgraph
  *

source/blender/depsgraph/intern/depsgraph_build.cc

@@ -22,8 +22,12 @@
  * Contributor(s): Based on original depsgraph.c code - Blender Foundation (2005-2013)
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_build.cc
+ *  \ingroup depsgraph
  *
- * Methods for constructing depsgraph
+ * Methods for constructing depsgraph.
  */
 
 #include <stack>

source/blender/depsgraph/intern/depsgraph_build.h

@@ -24,6 +24,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/depsgraph/intern/depsgraph_build.h
+ *  \ingroup depsgraph
+ */
+
 #ifndef __DEPSGRAPH_BUILD_H__
 #define __DEPSGRAPH_BUILD_H__
 

source/blender/depsgraph/intern/depsgraph_build_nodes.cc

@@ -22,11 +22,14 @@
  * Contributor(s): Based on original depsgraph.c code - Blender Foundation (2005-2013)
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_build_nodes.cc
+ *  \ingroup depsgraph
  *
  * Methods for constructing depsgraph's nodes
  */
 
-
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -525,7 +528,6 @@ void DepsgraphNodeBuilder::build_pose_constraints(Object *ob, bPoseChannel *pcha
 
 /**
  * Build graph nodes for AnimData block
- * \param scene_node: Scene that ID-block this lives on belongs to
  * \param id: ID-Block which hosts the AnimData
  */
 void DepsgraphNodeBuilder::build_animdata(ID *id)

source/blender/depsgraph/intern/depsgraph_build_relations.cc

@@ -22,6 +22,10 @@
  * Contributor(s): Based on original depsgraph.c code - Blender Foundation (2005-2013)
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_build_relations.cc
+ *  \ingroup depsgraph
  *
  * Methods for constructing depsgraph
  */

source/blender/depsgraph/intern/depsgraph_debug.cc

@@ -22,6 +22,10 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_debug.cc
+ *  \ingroup depsgraph
  *
  * Implementation of tools for debugging the depsgraph
  */

source/blender/depsgraph/intern/depsgraph_debug.h

@@ -24,6 +24,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/depsgraph/intern/depsgraph_debug.h
+ *  \ingroup depsgraph
+ */
+
 #ifndef __DEPSGRAPH_DEBUG_H__
 #define __DEPSGRAPH_DEBUG_H__
 

source/blender/depsgraph/intern/depsgraph_eval.cc

@@ -22,8 +22,12 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_eval.cc
+ *  \ingroup depsgraph
  *
- * Evaluation engine entrypoints for Depsgraph Engine
+ * Evaluation engine entrypoints for Depsgraph Engine.
  */
 
 #include "MEM_guardedalloc.h"

source/blender/depsgraph/intern/depsgraph_intern.h

@@ -22,6 +22,10 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_intern.h
+ *  \ingroup depsgraph
  *
  * API's for internal use in the Depsgraph
  * - Also, defines for "Node Type Info"

source/blender/depsgraph/intern/depsgraph_query.cc

@@ -22,6 +22,10 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_query.cc
+ *  \ingroup depsgraph
  *
  * Implementation of Querying and Filtering API's
  */

source/blender/depsgraph/intern/depsgraph_queue.cc

@@ -22,8 +22,12 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_queue.cc
+ *  \ingroup depsgraph
  *
- * Implementation of special queue type for use in Depsgraph traversals
+ * Implementation of special queue type for use in Depsgraph traversals.
  */
 
 #include <stdlib.h>

source/blender/depsgraph/intern/depsgraph_queue.h

@@ -22,8 +22,12 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_queue.h
+ *  \ingroup depsgraph
  *
- * Defines for special queue type for use in Depsgraph traversals
+ * Defines for special queue type for use in Depsgraph traversals.
  */
 
 #ifndef __DEPSGRAPH_QUEUE_H__

source/blender/depsgraph/intern/depsgraph_tag.cc

@@ -22,8 +22,12 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_tag.cc
+ *  \ingroup depsgraph
  *
- * Core routines for how the Depsgraph works
+ * Core routines for how the Depsgraph works.
  */
 
 #include <stdio.h>

source/blender/depsgraph/intern/depsgraph_type_defines.cc

@@ -22,8 +22,12 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_type_defines.cc
+ *  \ingroup depsgraph
  *
- * Defines and code for core node types
+ * Defines and code for core node types.
  */
 
 extern "C" {

source/blender/depsgraph/intern/depsgraph_types.h

@@ -22,6 +22,10 @@
  * Contributor(s): None Yet
  *
  * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/intern/depsgraph_types.h
+ *  \ingroup depsgraph
  *
  * Datatypes for internal use in the Depsgraph
  *

source/blender/depsgraph/intern/depsnode.cc

@@ -24,6 +24,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/depsgraph/intern/depsnode.cc
+ *  \ingroup depsgraph
+ */
+
 #include <stdio.h>
 #include <string.h>
 

source/blender/depsgraph/intern/depsnode.h

@@ -24,6 +24,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/depsgraph/intern/depsnode.h
+ *  \ingroup depsgraph
+ */
+
 #ifndef __DEPSNODE_H__
 #define __DEPSNODE_H__
 

source/blender/depsgraph/intern/depsnode_component.cc

@@ -24,6 +24,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/depsgraph/intern/depsnode_component.cc
+ *  \ingroup depsgraph
+ */
+
 #include <stdio.h>
 #include <string.h>
 

source/blender/depsgraph/intern/depsnode_component.h

@@ -24,6 +24,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/depsgraph/intern/depsnode_component.h
+ *  \ingroup depsgraph
+ */
+
 #ifndef __DEPSNODE_COMPONENT_H__
 #define __DEPSNODE_COMPONENT_H__
 

source/blender/depsgraph/intern/depsnode_opcodes.h

@@ -24,7 +24,11 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/* == OpCodes for OperationDepsNodes ==
+/** \file blender/depsgraph/intern/depsnode_opcodes.h
+ *  \ingroup depsgraph
+ *
+ * \par OpCodes for OperationDepsNodes
+ *
  * This file defines all the "operation codes" (opcodes) used to identify
  * common operation node types. The intention of these defines is to have
  * a fast and reliable way of identifying the relevant nodes within a component

source/blender/depsgraph/intern/depsnode_operation.cc

@@ -24,6 +24,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/depsgraph/intern/depsnode_operation.cc
+ *  \ingroup depsgraph
+ */
+
 #include "MEM_guardedalloc.h"
 
 extern "C" {

source/blender/depsgraph/intern/depsnode_operation.h

@@ -24,6 +24,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/depsgraph/intern/depsnode_operation.h
+ *  \ingroup depsgraph
+ */
+
 #ifndef __DEPSNODE_OPERATION_H__
 #define __DEPSNODE_OPERATION_H__
 

source/blender/depsgraph/util/depsgraph_util_cycle.cc

@@ -19,6 +19,12 @@
  * All rights reserved.
  *
  * Contributor(s): Sergey Sharybin
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/util/depsgraph_util_cycle.cc
+ *  \ingroup depsgraph
  */
 
 #include <cstdio>

source/blender/depsgraph/util/depsgraph_util_cycle.h

@@ -19,6 +19,12 @@
  * All rights reserved.
  *
  * Contributor(s): Sergey Sharybin
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/util/depsgraph_util_cycle.h
+ *  \ingroup depsgraph
  */
 
 #ifndef __DEPSGRAPH_UTIL_CYCLE_H__

source/blender/depsgraph/util/depsgraph_util_function.h

@@ -20,6 +20,12 @@
  *
  * Original Author: Lukas Toenne
  * Contributor(s): 
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/util/depsgraph_util_function.h
+ *  \ingroup depsgraph
  */
 
 #ifndef __DEPSGRAPH_UTIL_FUNCTION_H__

source/blender/depsgraph/util/depsgraph_util_hash.h

@@ -20,6 +20,12 @@
  *
  * Original Author: Brecht van Lommel
  * Contributor(s): Lukas Toenne
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/util/depsgraph_util_hash.h
+ *  \ingroup depsgraph
  */
 
 #ifndef __DEPSGRAPH_UTIL_HASH_H__

source/blender/depsgraph/util/depsgraph_util_map.h

@@ -20,6 +20,12 @@
  *
  * Original Author: Brecht van Lommel
  * Contributor(s): Lukas Toenne
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/util/depsgraph_util_map.h
+ *  \ingroup depsgraph
  */
 
 #ifndef __DEPSGRAPH_UTIL_MAP_H__

source/blender/depsgraph/util/depsgraph_util_pchanmap.cc

@@ -24,6 +24,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/depsgraph/util/depsgraph_util_pchanmap.cc
+ *  \ingroup depsgraph
+ */
+
 #include "depsgraph_util_pchanmap.h"
 
 #include <stdio.h>

source/blender/depsgraph/util/depsgraph_util_pchanmap.h

@@ -24,6 +24,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/depsgraph/util/depsgraph_util_pchanmap.h
+ *  \ingroup depsgraph
+ */
+
 #ifndef __DEPSGRAPH_UTIL_PCHANMAP_H__
 #define __DEPSGRAPH_UTIL_PCHANMAP_H__
 

source/blender/depsgraph/util/depsgraph_util_set.h

@@ -20,6 +20,12 @@
  *
  * Original Author: Brecht van Lommel
  * Contributor(s): Lukas Toenne
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/util/depsgraph_util_set.h
+ *  \ingroup depsgraph
  */
 
 #ifndef __DEPSGRAPH_UTIL_SET_H__

source/blender/depsgraph/util/depsgraph_util_transitive.cc

@@ -18,8 +18,14 @@
  * The Original Code is Copyright (C) 2015 Blender Foundation.
  * All rights reserved.
  *
- * Contributor(s): Lukas Toenne
+ * Contributor(s): Lukas Toenne,
  *                 Sergey Sharybin,
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/util/depsgraph_util_transitive.cc
+ *  \ingroup depsgraph
  */
 
 extern "C" {

source/blender/depsgraph/util/depsgraph_util_transitive.h

@@ -20,6 +20,12 @@
  *
  * Contributor(s): Lukas Toenne
  *                 Sergey Sharybin,
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/depsgraph/util/depsgraph_util_transitive.h
+ *  \ingroup depsgraph
  */
 
 #ifndef __DEPSGRAPH_UTIL_TRANSITIVE_H__

source/blender/editors/interface/view2d.c

@@ -1987,7 +1987,7 @@ void UI_view2d_listview_view_to_cell(
  *
  * \param columnwidth, rowheight: Size of each 'cell'
  * \param startx, starty: Coordinates that the list starts from, which should be (0,0) for most views
- * \param column, row_min, max: The starting and ending column/row indices
+ * \param column_min, column_max, row_min, row_max: The starting and ending column/row indices
  */
 void UI_view2d_listview_visible_cells(
         View2D *v2d, float columnwidth, float rowheight, float startx, float starty,
@@ -2021,7 +2021,7 @@ float UI_view2d_region_to_view_y(struct View2D *v2d, float y)
  * Convert from screen/region space to 2d-View space
  *
  * \param x, y: coordinates to convert
- * \param viewx, viewy: resultant coordinates
+ * \param r_view_x, r_view_y: resultant coordinates
  */
 void UI_view2d_region_to_view(View2D *v2d, float x, float y, float *r_view_x, float *r_view_y)
 {
@@ -2054,7 +2054,7 @@ float UI_view2d_view_to_region_y(View2D *v2d, float y)
  * \note Coordinates are clamped to lie within bounds of region
  *
  * \param x, y: Coordinates to convert.
- * \param regionx, regiony: Resultant coordinates.
+ * \param r_region_x, r_region_y: Resultant coordinates.
  */
 bool UI_view2d_view_to_region_clip(View2D *v2d, float x, float y, int *r_region_x, int *r_region_y)
 {
@@ -2083,7 +2083,7 @@ bool UI_view2d_view_to_region_clip(View2D *v2d, float x, float y, int *r_region_
  * \note Coordinates are NOT clamped to lie within bounds of region.
  *
  * \param x, y: Coordinates to convert.
- * \param regionx, regiony: Resultant coordinates.
+ * \param r_region_x, r_region_y: Resultant coordinates.
  */
 void UI_view2d_view_to_region(View2D *v2d, float x, float y, int *r_region_x, int *r_region_y)
 {

source/blender/editors/sculpt_paint/sculpt.c

@@ -373,6 +373,9 @@ static void sculpt_project_v3_cache_init(
 	spvc->len_sq_inv_neg = (spvc->is_valid) ? -1.0f / spvc->len_sq : 0.0f;
 }
 
+/**
+ * Calculate the projection.
+ */
 static void sculpt_project_v3(
         const SculptProjectVector *spvc, const float vec[3],
         float r_vec[3])

source/blender/imbuf/IMB_imbuf.h

@@ -38,21 +38,21 @@
  * \page IMB Imbuf module external interface
  *
  *
- * \section about About the IMB module
+ * \section imb_about About the IMB module
  *
  * External interface of the IMage Buffer module. This module offers
  * import/export of several graphical file formats. It offers the
  * ImBuf type as a common structure to refer to different graphical
  * file formats, and to enable a uniform way of handling them.
  *
- * \section issues Known issues with IMB
+ * \section imb_issues Known issues with IMB
  *
  * - imbuf is written in C.
  * - Endianness issues are dealt with internally.
  * - File I/O must be done externally. The module uses FILE*'s to
  *   direct input/output.
  *
- * \section dependencies Dependencies
+ * \section imb_dependencies Dependencies
  *
  * IMB needs:
  * - \ref DNA module

source/blender/physics/BPH_mass_spring.h

@@ -25,6 +25,10 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/physics/intern/BPH_mass_spring.h
+ *  \ingroup bph
+ */
+
 #ifndef __BPH_MASS_SPRING_H__
 #define __BPH_MASS_SPRING_H__
 

source/blender/physics/intern/eigen_utils.h

@@ -28,7 +28,7 @@
 #ifndef __EIGEN_UTILS_H__
 #define __EIGEN_UTILS_H__
 
-/** \file eigen_utils.h
+/** \file blender/physics/intern/eigen_utils.h
  *  \ingroup bph
  */
 

source/gameengine/Expressions/PyObjectPlus.cpp

@@ -158,7 +158,8 @@ PyObject *PyObjectPlus::py_base_new(PyTypeObject *type, PyObject *args, PyObject
 
 	PyObjectPlus_Proxy *base = (PyObjectPlus_Proxy *)PyTuple_GET_ITEM(args, 0);
 
-	/* the 'base' PyObject may be subclassed (multiple times even)
+	/**
+	 * the 'base' PyObject may be subclassed (multiple times even)
 	 * we need to find the first C++ defined class to check 'type'
 	 * is a subclass of the base arguments type.
 	 *
@@ -167,12 +168,13 @@ PyObject *PyObjectPlus::py_base_new(PyTypeObject *type, PyObject *args, PyObject
 	 * eg.
 	 *
 	 * # CustomOb is called 'type' in this C code
+	 * \code{.py}
 	 * class CustomOb(GameTypes.KX_GameObject):
 	 *     pass
 	 *
 	 * # this calls py_base_new(...), the type of 'CustomOb' is checked to be a subclass of the 'cont.owner' type
 	 * ob = CustomOb(cont.owner)
-	 *
+	 * \endcode
 	 * */
 	base_type= Py_TYPE(base);
 	while (base_type && !BGE_PROXY_CHECK_TYPE(base_type))