Docs: doxygen file descriptions for BLF, GPU and WM

source/blender/blenfont/intern/blf.c

@@ -26,6 +26,10 @@
 
 /** \file blender/blenfont/intern/blf.c
  *  \ingroup blf
+ *
+ * Main BlenFont (BLF) API, public functions for font handling.
+ *
+ * Wraps OpenGL and FreeType.
  */
 
 #include <stdio.h>

source/blender/blenfont/intern/blf_dir.c

@@ -25,6 +25,8 @@
 
 /** \file blender/blenfont/intern/blf_dir.c
  *  \ingroup blf
+ *
+ * Manage search paths for font files.
  */
 
 

source/blender/blenfont/intern/blf_font.c

@@ -26,6 +26,10 @@
 
 /** \file blender/blenfont/intern/blf_font.c
  *  \ingroup blf
+ *
+ * Deals with drawing text to OpenGL or bitmap buffers.
+ *
+ * Also low level functions for managing \a FontBLF.
  */
 
 

source/blender/blenfont/intern/blf_glyph.c

@@ -26,6 +26,8 @@
 
 /** \file blender/blenfont/intern/blf_glyph.c
  *  \ingroup blf
+ *
+ * Glyph rendering, texturing and caching. Wraps Freetype and OpenGL functions.
  */
 
 

source/blender/blenfont/intern/blf_lang.c

@@ -25,6 +25,8 @@
 
 /** \file blender/blenfont/intern/blf_lang.c
  *  \ingroup blf
+ *
+ * Main internationalization functions to set the locale and query available languages.
  */
 
 #include <stdio.h>

source/blender/blenfont/intern/blf_translation.c

@@ -26,6 +26,9 @@
 
 /** \file blender/blenfont/intern/blf_translation.c
  *  \ingroup blf
+ *
+ * Manages translation files and provides translation functions.
+ * (which are optional and can be disabled as a preference).
  */
 
 #include <stdlib.h>

source/blender/blenfont/intern/blf_util.c

@@ -26,6 +26,8 @@
 
 /** \file blender/blenfont/intern/blf_util.c
  *  \ingroup blf
+ *
+ * Internal utility API for BLF.
  */
 
 

source/blender/blenlib/intern/task.c

@@ -18,6 +18,12 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/blenlib/intern/task.c
+ *  \ingroup bli
+ *
+ * A generic task system which can be used for any task based subsystem.
+ */
+
 #include <stdlib.h>
 
 #include "MEM_guardedalloc.h"

source/blender/bmesh/intern/bmesh_core.c

@@ -23,6 +23,7 @@
 /** \file blender/bmesh/intern/bmesh_core.c
  *  \ingroup bmesh
  *
+ * Core BMesh functions for adding, removing BMesh elements.
  */
 
 #include "MEM_guardedalloc.h"

source/blender/bmesh/tools/bmesh_bevel.c

@@ -26,6 +26,8 @@
 
 /** \file blender/bmesh/tools/bmesh_bevel.c
  *  \ingroup bmesh
+ *
+ * Main functions for beveling a BMesh (used by the tool and modifier)
  */
 
 #include "MEM_guardedalloc.h"

source/blender/gpu/intern/gpu_buffers.c

@@ -27,9 +27,11 @@
 
 /** \file blender/gpu/intern/gpu_buffers.c
  *  \ingroup gpu
+ *
+ * Mesh drawing using OpenGL VBO (Vertex Buffer Objects),
+ * with fall-back to vertex arrays.
  */
 
-
 #include <limits.h>
 #include <stddef.h>
 #include <string.h>

source/blender/gpu/intern/gpu_codegen.c

@@ -27,9 +27,10 @@
 
 /** \file blender/gpu/intern/gpu_codegen.c
  *  \ingroup gpu
+ *
+ * Convert material node-trees to GLSL.
  */
 
-
 #include "GL/glew.h"
 
 #include "MEM_guardedalloc.h"

source/blender/gpu/intern/gpu_draw.c

@@ -27,9 +27,15 @@
 
 /** \file blender/gpu/intern/gpu_draw.c
  *  \ingroup gpu
+ *
+ * Utility functions for dealing with OpenGL texture & material context,
+ * mipmap generation and light objects.
+ *
+ * These are some obscure rendering functions shared between the
+ * game engine and the blender, in this module to avoid duplication
+ * and abstract them away from the rest a bit.
  */
 
-
 #include <string.h>
 
 #include "GL/glew.h"
@@ -74,10 +80,6 @@
 
 extern Material defmaterial; /* from material.c */
 
-/* These are some obscure rendering functions shared between the
- * game engine and the blender, in this module to avoid duplicaten
- * and abstract them away from the rest a bit */
-
 /* Text Rendering */
 
 static void gpu_mcol(unsigned int ucol)

source/blender/gpu/intern/gpu_extensions.c

@@ -27,6 +27,9 @@
 
 /** \file blender/gpu/intern/gpu_extensions.c
  *  \ingroup gpu
+ *
+ * Wrap OpenGL features such as textures, shaders and GLSL
+ * with checks for drivers and GPU support.
  */
 
 

source/blender/gpu/intern/gpu_material.c

@@ -27,6 +27,8 @@
 
 /** \file blender/gpu/intern/gpu_material.c
  *  \ingroup gpu
+ *
+ * Manages materials, lights and textures.
  */
 
 

source/blender/gpu/intern/gpu_simple_shader.c

@@ -27,9 +27,8 @@
 
 /** \file blender/gpu/intern/gpu_simple_shader.c
  *  \ingroup gpu
- */
-
-/* GLSL shaders to replace fixed function OpenGL materials and lighting. These
+ *
+ * GLSL shaders to replace fixed function OpenGL materials and lighting. These
  * are deprecated in newer OpenGL versions and missing in OpenGL ES 2.0. Also,
  * two sided lighting is no longer natively supported on NVidia cards which
  * results in slow software fallback.

source/blender/windowmanager/WM_api.h

@@ -87,7 +87,7 @@ void		WM_init_splash		(struct bContext *C);
 
 void		WM_check			(struct bContext *C);
 
-struct wmWindow	*WM_window_open	(struct bContext *C, struct rcti *rect);
+struct wmWindow	*WM_window_open	(struct bContext *C, const struct rcti *rect);
 
 int			WM_window_pixels_x		(struct wmWindow *win);
 int			WM_window_pixels_y		(struct wmWindow *win);
@@ -137,7 +137,7 @@ int			WM_userdef_event_map(int kmitype);
 
 struct wmEventHandler *WM_event_add_keymap_handler(ListBase *handlers, wmKeyMap *keymap);
 						/* boundbox, optional subwindow boundbox for offset */
-struct wmEventHandler *WM_event_add_keymap_handler_bb(ListBase *handlers, wmKeyMap *keymap, rcti *bb, rcti *swinbb);
+struct wmEventHandler *WM_event_add_keymap_handler_bb(ListBase *handlers, wmKeyMap *keymap, const rcti *bb, const rcti *swinbb);
 						/* priority not implemented, it adds in begin */
 struct wmEventHandler *WM_event_add_keymap_handler_priority(ListBase *handlers, wmKeyMap *keymap, int priority);
 

source/blender/windowmanager/intern/wm.c

@@ -26,6 +26,10 @@
 
 /** \file blender/windowmanager/intern/wm.c
  *  \ingroup wm
+ *
+ * Internal functions for managing UI registrable types (operator, UI and menu types)
+ *
+ * Also Blenders main event loop (WM_main)
  */
 
 #include <string.h>

source/blender/windowmanager/intern/wm_cursors.c

@@ -27,9 +27,10 @@
 
 /** \file blender/windowmanager/intern/wm_cursors.c
  *  \ingroup wm
+ *
+ * Cursor pixmap and cursor utility functions to change the cursor.
  */
 
-
 #include <stdio.h>
 #include <string.h>
 

source/blender/windowmanager/intern/wm_dragdrop.c

@@ -26,9 +26,10 @@
 
 /** \file blender/windowmanager/intern/wm_dragdrop.c
  *  \ingroup wm
+ *
+ * Our own drag-and-drop, drag state and drop boxes.
  */
 
-
 #include <string.h>
 
 #include "DNA_windowmanager_types.h"

source/blender/windowmanager/intern/wm_draw.c

@@ -26,9 +26,10 @@
 
 /** \file blender/windowmanager/intern/wm_draw.c
  *  \ingroup wm
+ *
+ * Handle OpenGL buffers for windowing, also paint cursor.
  */
 
-
 #include <stdlib.h>
 #include <string.h>
 #include <GL/glew.h>

source/blender/windowmanager/intern/wm_event_system.c

@@ -26,6 +26,10 @@
 
 /** \file blender/windowmanager/intern/wm_event_system.c
  *  \ingroup wm
+ *
+ * Handle events and notifiers from GHOST input (mouse, keyboard, tablet, ndof).
+ *
+ * Also some operator reports utility functions.
  */
 
 
@@ -2457,7 +2461,7 @@ wmEventHandler *WM_event_add_keymap_handler_priority(ListBase *handlers, wmKeyMa
 	return handler;
 }
 
-wmEventHandler *WM_event_add_keymap_handler_bb(ListBase *handlers, wmKeyMap *keymap, rcti *bblocal, rcti *bbwin)
+wmEventHandler *WM_event_add_keymap_handler_bb(ListBase *handlers, wmKeyMap *keymap, const rcti *bblocal, const rcti *bbwin)
 {
 	wmEventHandler *handler = WM_event_add_keymap_handler(handlers, keymap);
 	

source/blender/windowmanager/intern/wm_files.c

@@ -25,6 +25,8 @@
 
 /** \file blender/windowmanager/intern/wm_files.c
  *  \ingroup wm
+ *
+ * User level access for blend file read/write, file-history and userprefs.
  */
 
 
@@ -62,7 +64,6 @@
 #include "BLF_translation.h"
 
 #include "DNA_anim_types.h"
-#include "DNA_ipo_types.h" // XXX old animation system
 #include "DNA_object_types.h"
 #include "DNA_space_types.h"
 #include "DNA_userdef_types.h"
@@ -1144,6 +1145,3 @@ void wm_autosave_read(bContext *C, ReportList *reports)
 	WM_file_read(C, filename, reports);
 }
 
-
-
-

source/blender/windowmanager/intern/wm_gesture.c

@@ -26,9 +26,10 @@
 
 /** \file blender/windowmanager/intern/wm_gesture.c
  *  \ingroup wm
+ *
+ * Gestures (cursor motions) creating, evaluating and drawing, shared between operators.
  */
 
-
 #include "DNA_screen_types.h"
 #include "DNA_vec_types.h"
 #include "DNA_userdef_types.h"
@@ -38,7 +39,6 @@
 
 #include "BLI_blenlib.h"
 #include "BLI_math.h"
-#include "BLI_scanfill.h"   /* lasso tessellation */
 #include "BLI_utildefines.h"
 #include "BLI_lasso.h"
 

source/blender/windowmanager/intern/wm_init_exit.c

@@ -26,6 +26,8 @@
 
 /** \file blender/windowmanager/intern/wm_init_exit.c
  *  \ingroup wm
+ *
+ * Manage initializing resources and correctly shutting down.
  */
 
 #include <stdlib.h>

source/blender/windowmanager/intern/wm_jobs.c

@@ -26,9 +26,10 @@
 
 /** \file blender/windowmanager/intern/wm_jobs.c
  *  \ingroup wm
+ *
+ * Threaded job manager (high level job access).
  */
 
-
 #include <string.h>
 
 #include "DNA_windowmanager_types.h"
@@ -56,8 +57,6 @@
 
 #include "PIL_time.h"
 
-/* ********************** Threaded Jobs Manager ****************************** */
-
 /*
  * Add new job
  * - register in WM

source/blender/windowmanager/intern/wm_keymap.c

@@ -26,9 +26,10 @@
 
 /** \file blender/windowmanager/intern/wm_keymap.c
  *  \ingroup wm
+ *
+ * Configurable key-maps - add/remove/find/compare/patch...
  */
 
-
 #include <string.h>
 
 #include "DNA_object_types.h"

source/blender/windowmanager/intern/wm_operators.c

@@ -26,6 +26,9 @@
 
 /** \file blender/windowmanager/intern/wm_operators.c
  *  \ingroup wm
+ *
+ * Functions for dealing with wmOperator, adding, removing, calling
+ * as well as some generic operators and shared operator properties.
  */
 
 

source/blender/windowmanager/intern/wm_subwindow.c

@@ -30,9 +30,10 @@
 
 /** \file blender/windowmanager/intern/wm_subwindow.c
  *  \ingroup wm
+ *
+ * Internal subwindows used for OpenGL state, used for regions and screens.
  */
 
-
 #include <string.h>
 
 #include "MEM_guardedalloc.h"

source/blender/windowmanager/intern/wm_window.c

@@ -26,6 +26,8 @@
 
 /** \file blender/windowmanager/intern/wm_window.c
  *  \ingroup wm
+ *
+ * Window management, wrap GHOST.
  */
 
 #include <math.h>
@@ -482,7 +484,7 @@ void wm_window_add_ghostwindows(wmWindowManager *wm)
 /* new window, no screen yet, but we open ghostwindow for it */
 /* also gets the window level handlers */
 /* area-rip calls this */
-wmWindow *WM_window_open(bContext *C, rcti *rect)
+wmWindow *WM_window_open(bContext *C, const rcti *rect)
 {
 	wmWindow *win = wm_window_new(C);
 	

source/blender/windowmanager/wm_event_system.h

@@ -50,7 +50,7 @@ typedef struct wmEventHandler {
 
 	/* keymap handler */
 	wmKeyMap *keymap;                   /* pointer to builtin/custom keymaps */
-	rcti *bblocal, *bbwin;              /* optional local and windowspace bb */
+	const rcti *bblocal, *bbwin;              /* optional local and windowspace bb */
 
 	/* modal operator handler */
 	wmOperator *op;                     /* for derived/modal handlers */