Docs: doxygen file descriptions for BLF, GPU and WM

31 files changed, 83 insertions, 29 deletions

diff --git a/source/blender/blenfont/intern/blf.c b/source/blender/blenfont/intern/blf.c
index 0b6231e5b23..54f94ad7b87 100644
--- a/source/blender/blenfont/intern/blf.c
+++ b/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>
diff --git a/source/blender/blenfont/intern/blf_dir.c b/source/blender/blenfont/intern/blf_dir.c
index da4d0b77a73..4a36ae03bed 100644
--- a/source/blender/blenfont/intern/blf_dir.c
+++ b/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.
  */
 
 
diff --git a/source/blender/blenfont/intern/blf_font.c b/source/blender/blenfont/intern/blf_font.c
index 5864c17fac4..846c9cca55c 100644
--- a/source/blender/blenfont/intern/blf_font.c
+++ b/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.
  */
 
 
diff --git a/source/blender/blenfont/intern/blf_glyph.c b/source/blender/blenfont/intern/blf_glyph.c
index 248c645edc0..7c3cfa30e16 100644
--- a/source/blender/blenfont/intern/blf_glyph.c
+++ b/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.
  */
 
 
diff --git a/source/blender/blenfont/intern/blf_lang.c b/source/blender/blenfont/intern/blf_lang.c
index 9649e5bc746..623d8b7652a 100644
--- a/source/blender/blenfont/intern/blf_lang.c
+++ b/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>
diff --git a/source/blender/blenfont/intern/blf_translation.c b/source/blender/blenfont/intern/blf_translation.c
index 57f442f8bfc..dc9baf804b3 100644
--- a/source/blender/blenfont/intern/blf_translation.c
+++ b/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>
diff --git a/source/blender/blenfont/intern/blf_util.c b/source/blender/blenfont/intern/blf_util.c
index 8240906dd3b..cb9b652b8ef 100644
--- a/source/blender/blenfont/intern/blf_util.c
+++ b/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.
  */
 
 
diff --git a/source/blender/blenlib/intern/task.c b/source/blender/blenlib/intern/task.c
index 4ae60abb2c8..1ac4045ea49 100644
--- a/source/blender/blenlib/intern/task.c
+++ b/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"
diff --git a/source/blender/bmesh/intern/bmesh_core.c b/source/blender/bmesh/intern/bmesh_core.c
index 7b3ca898718..c635f9d9d06 100644
--- a/source/blender/bmesh/intern/bmesh_core.c
+++ b/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"
diff --git a/source/blender/bmesh/tools/bmesh_bevel.c b/source/blender/bmesh/tools/bmesh_bevel.c
index d07d833eab9..9f2a71e7e29 100644
--- a/source/blender/bmesh/tools/bmesh_bevel.c
+++ b/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"
diff --git a/source/blender/gpu/intern/gpu_buffers.c b/source/blender/gpu/intern/gpu_buffers.c
index f6919e34790..6a6979ed89f 100644
--- a/source/blender/gpu/intern/gpu_buffers.c
+++ b/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>
diff --git a/source/blender/gpu/intern/gpu_codegen.c b/source/blender/gpu/intern/gpu_codegen.c
index 8e0d0e55709..ecd4ad6f0c3 100644
--- a/source/blender/gpu/intern/gpu_codegen.c
+++ b/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"
diff --git a/source/blender/gpu/intern/gpu_draw.c b/source/blender/gpu/intern/gpu_draw.c
index f3f304b0e04..5ee30c242c1 100644
--- a/source/blender/gpu/intern/gpu_draw.c
+++ b/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)
diff --git a/source/blender/gpu/intern/gpu_extensions.c b/source/blender/gpu/intern/gpu_extensions.c
index 1d08f1f6ea9..e8fd8eb49d6 100644
--- a/source/blender/gpu/intern/gpu_extensions.c
+++ b/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.
  */
 
 
diff --git a/source/blender/gpu/intern/gpu_material.c b/source/blender/gpu/intern/gpu_material.c
index a746ac63bda..a425153f403 100644
--- a/source/blender/gpu/intern/gpu_material.c
+++ b/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.
  */
 
 
diff --git a/source/blender/gpu/intern/gpu_simple_shader.c b/source/blender/gpu/intern/gpu_simple_shader.c
index 5fb723172ec..0cb712d220f 100644
--- a/source/blender/gpu/intern/gpu_simple_shader.c
+++ b/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.
diff --git a/source/blender/windowmanager/WM_api.h b/source/blender/windowmanager/WM_api.h
index 046152d07a1..b635544add0 100644
--- a/source/blender/windowmanager/WM_api.h
+++ b/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);
 
diff --git a/source/blender/windowmanager/intern/wm.c b/source/blender/windowmanager/intern/wm.c
index 2fbf92ebed7..6a91eca2c7f 100644
--- a/source/blender/windowmanager/intern/wm.c
+++ b/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>
diff --git a/source/blender/windowmanager/intern/wm_cursors.c b/source/blender/windowmanager/intern/wm_cursors.c
index 09a83834610..01cd1514a3a 100644
--- a/source/blender/windowmanager/intern/wm_cursors.c
+++ b/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>
 
diff --git a/source/blender/windowmanager/intern/wm_dragdrop.c b/source/blender/windowmanager/intern/wm_dragdrop.c
index 12e23c3d0c7..7675d4d4418 100644
--- a/source/blender/windowmanager/intern/wm_dragdrop.c
+++ b/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"
diff --git a/source/blender/windowmanager/intern/wm_draw.c b/source/blender/windowmanager/intern/wm_draw.c
index b4d29f05e15..e89980f53fc 100644
--- a/source/blender/windowmanager/intern/wm_draw.c
+++ b/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>
diff --git a/source/blender/windowmanager/intern/wm_event_system.c b/source/blender/windowmanager/intern/wm_event_system.c
index f8488b63c85..308c14814af 100644
--- a/source/blender/windowmanager/intern/wm_event_system.c
+++ b/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);
 	
diff --git a/source/blender/windowmanager/intern/wm_files.c b/source/blender/windowmanager/intern/wm_files.c
index 9c479a2b868..55f0d922005 100644
--- a/source/blender/windowmanager/intern/wm_files.c
+++ b/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);
 }
 
-
-
-
diff --git a/source/blender/windowmanager/intern/wm_gesture.c b/source/blender/windowmanager/intern/wm_gesture.c
index 83cb6fd83d1..6e34c776719 100644
--- a/source/blender/windowmanager/intern/wm_gesture.c
+++ b/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"
 
diff --git a/source/blender/windowmanager/intern/wm_init_exit.c b/source/blender/windowmanager/intern/wm_init_exit.c
index 8b43a6af606..5196b584816 100644
--- a/source/blender/windowmanager/intern/wm_init_exit.c
+++ b/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>
diff --git a/source/blender/windowmanager/intern/wm_jobs.c b/source/blender/windowmanager/intern/wm_jobs.c
index 7da9a1c09d3..4cf5813d080 100644
--- a/source/blender/windowmanager/intern/wm_jobs.c
+++ b/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
diff --git a/source/blender/windowmanager/intern/wm_keymap.c b/source/blender/windowmanager/intern/wm_keymap.c
index 4758ba5d775..36099d5de8e 100644
--- a/source/blender/windowmanager/intern/wm_keymap.c
+++ b/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"
diff --git a/source/blender/windowmanager/intern/wm_operators.c b/source/blender/windowmanager/intern/wm_operators.c
index 38e9b6d7d33..255d6f19789 100644
--- a/source/blender/windowmanager/intern/wm_operators.c
+++ b/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.
  */
 
 
diff --git a/source/blender/windowmanager/intern/wm_subwindow.c b/source/blender/windowmanager/intern/wm_subwindow.c
index 75608a850ac..10a24338b35 100644
--- a/source/blender/windowmanager/intern/wm_subwindow.c
+++ b/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"
diff --git a/source/blender/windowmanager/intern/wm_window.c b/source/blender/windowmanager/intern/wm_window.c
index 1e682be603b..f2f9443c111 100644
--- a/source/blender/windowmanager/intern/wm_window.c
+++ b/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);
 	
diff --git a/source/blender/windowmanager/wm_event_system.h b/source/blender/windowmanager/wm_event_system.h
index cc139f33c84..df084554c54 100644
--- a/source/blender/windowmanager/wm_event_system.h
+++ b/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 */