From f697247f0e567f87dcce76fa389c9b6a62fcef6a Mon Sep 17 00:00:00 2001
From: Nathan Letwory <nathan@letworyinteractive.com>
Date: Thu, 17 Feb 2011 16:17:40 +0000
Subject: [PATCH] Start simple intros for intern and extern libs. Some reorg of
 modules/pages, start makesdna and makesrna. In many places license block
 needs to be changed to not start with /**, because otherwise documentation
 will go weird.

---
 doc/doxygen.main                            | 56 +++++++++++++--------
 intern/ghost/GHOST_ISystem.h                |  9 +---
 source/blender/makesdna/DNA_documentation.h | 14 +++---
 source/blender/makesdna/DNA_sdna_types.h    |  8 +--
 source/blender/makesdna/intern/makesdna.c   | 10 ++--
 source/blender/makesrna/RNA_documentation.h |  2 +-
 6 files changed, 58 insertions(+), 41 deletions(-)

diff --git a/doc/doxygen.main b/doc/doxygen.main
index 450ba8298ee..a34eb9d888d 100644
--- a/doc/doxygen.main
+++ b/doc/doxygen.main
@@ -2,23 +2,17 @@
  *
  * \section intro Introduction
  *
- * Blender is an integrated 3d package, which features:
- *  - modeling
- *  - animation
- *  - texturing
- *  - compositing
- *  - rendering
- *  - scripting
- *  - game creation
+ * Blender is an integrated 3d package.
  *
  * These pages document the source code of blender.
  *
+ * For more information on using Blender browse to http://www.blender.org
+ *
  * \section sects Main sections of the blender code
  *
  *  The following sections are the broad categories into which the various modules
  *  belong.
  *
- *  - \ref mainmodule
  *  - \ref render
  *  - \ref meshedit
  *  - \ref texture
@@ -41,22 +35,47 @@
  *  - \ref undoc
  */
 
-/** \defgroup mainmodule Main Module */
-/** \defgroup defaultconfig Default and Configuration
- *  \ingroup mainmodule
+/** \defgroup intern Internal libraries
+ *  \section internabout Internal libraries
+ *  Blender comes with some of its dependencies
+ *  directly included in the codebase. Libraries
+ *  that are in the \c intern/ folder are maintained
+ *  as part of the normal development process.
  */
 
+/** \defgroup extern External libraries
+ *  \section externabout External libraries
+ *  As with \ref intern these libraries are
+ *  provided in the Blender codebase. This is
+ *  to make building Blender easier. The main
+ *  development of these libraries is \b not part
+ *  of the normal Blender development process, but
+ *  each of the library is developed separately.
+ *  Whenever deemed necessary libraries in \c extern/
+ *  folder are updated.
+ *
+ */
+/** \defgroup editors Editor modules */
+/** \defgroup blenderplayer Blender Player */
+
 /** \defgroup render Rendering Module */
 /** \defgroup meshedit Mesh Editing Module */
 /** \defgroup texture Texturing */
 /** \defgroup compositor Compositing */
+
 /** \defgroup scripts Scripting */
+
 /** \defgroup gameengine Game Engine */
-/** \defgroup audaspace Audaspace */
+
+/** \defgroup audaspace Audaspace
+ *  \ingroup intern undoc
+ *  \todo add to doxygen
+ */
 
 /** \defgroup data DNA and RNA */
 
 /** \defgroup GHOST GHOST API */
+
 /** \defgroup DNA sDNA
  *  \ingroup data
  */
@@ -65,15 +84,12 @@
  */
 
 /** \defgroup gui GUI */
-/** \defgroup hotkeys Hotkeys
- *  \ingroup gui
- */
-/** \defgroup toolbox Toolbox
- *  \ingroup gui
- */
+
 /** \defgroup wm windowmanager
  *  \ingroup gui
  */
 
 /** \defgroup imbuf IMage Buffer */
-/** \defgroup undoc Undocumented */
+
+/** \defgroup undoc Undocumented
+ *  \brief Modules and libraries that are still undocumented, or lacking proper integration into the doxygen system, are marked in this group. */
diff --git a/intern/ghost/GHOST_ISystem.h b/intern/ghost/GHOST_ISystem.h
index b2b9fff6a4a..fce1ceca53b 100644
--- a/intern/ghost/GHOST_ISystem.h
+++ b/intern/ghost/GHOST_ISystem.h
@@ -25,6 +25,7 @@
  *
  * ***** END GPL LICENSE BLOCK *****
  */
+
 /*! \ingroup GHOST
  * \file	GHOST_ISystem.h
  * %Main interface file for C++ Api with declaration of GHOST_ISystem interface
@@ -88,8 +89,6 @@ class GHOST_IEventConsumer;
  * <ul>
  * <li>GHOST_IEvent.h</li>
  * <li>GHOST_IEventConsumer.h</li>
- * <li>GHOST_IMenu.h (in progress)</li>
- * <li>GHOST_IMenuBar.h (in progress)</li>
  * <li>GHOST_ISystem.h</li>
  * <li>GHOST_ITimerTask.h</li>
  * <li>GHOST_IWindow.h</li>
@@ -108,11 +107,7 @@ class GHOST_IEventConsumer;
  * in the ?/ghost/test/gears/ directory.
  *
  * \section work Work in progress
- *
- * \subsection menus Menu functionality
- * Menu bars with pull-down menu's for windows are in development in the 
- * current version of GHOST. The file GHOST_MenuDependKludge.h contains a 
- * setting to turn menu functionality on or off.
+ * \todo write WIP section
  */
  
 /** \interface GHOST_ISystem
diff --git a/source/blender/makesdna/DNA_documentation.h b/source/blender/makesdna/DNA_documentation.h
index cfca99fff6d..2e5eb3778c4 100644
--- a/source/blender/makesdna/DNA_documentation.h
+++ b/source/blender/makesdna/DNA_documentation.h
@@ -27,11 +27,11 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/*!
- *  \ingroup DNA
+/**
  *  \page makesdna makesdna
+ *  \ingroup DNA
  *
- * @section aboutdna About the DNA module
+ * \section aboutdna About the DNA module
  *
  * The DNA module holds all type definitions that are serialized in a
  * blender file. There is an executable that scans all files, looking
@@ -39,7 +39,7 @@
  * information, it builds a file with numbers that encode the format,
  * the names of variables, and the plce to look for them.
  *
- * @section dnaissues Known issues with DNA
+ * \section dnaissues Known issues with DNA
  *
  * - Function pointers:
  *
@@ -58,19 +58,19 @@
  *   have to change this (Not very flexible, but it is hardly ever
  *   changed. Sorry.).
  *
- * @section dnadependencies Dependencies
+ * \section dnadependencies Dependencies
  *
  * DNA has no external dependencies (except for a few system
  * includes).
 
- * @section dnanote NOTE
+ * \section dnanote NOTE
 
   PLEASE READ INSTRUCTIONS ABOUT ADDING VARIABLES IN 'DNA' STRUCTS IN
 
   intern/dna_genfile.c
   (ton)
 
- **/
+ */
 
 
 
diff --git a/source/blender/makesdna/DNA_sdna_types.h b/source/blender/makesdna/DNA_sdna_types.h
index 8e291035be7..e5f924b5fa6 100644
--- a/source/blender/makesdna/DNA_sdna_types.h
+++ b/source/blender/makesdna/DNA_sdna_types.h
@@ -1,6 +1,4 @@
-/**
- * blenlib/DNA_sdna.h (mar-2001 nzc)
- *	
+/*
  * $Id$ 
  *
  * ***** BEGIN GPL LICENSE BLOCK *****
@@ -30,6 +28,10 @@
  */
 #ifndef DNA_SDNA_H
 #define DNA_SDNA_H
+/**
+ * \file DNA_sdna_types.h
+ * \ingroup DNA
+ */
 
 #
 #
diff --git a/source/blender/makesdna/intern/makesdna.c b/source/blender/makesdna/intern/makesdna.c
index 471a1b86825..50083a3472c 100644
--- a/source/blender/makesdna/intern/makesdna.c
+++ b/source/blender/makesdna/intern/makesdna.c
@@ -27,8 +27,11 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** Struct muncher for making SDNA
+/**  \file makesdna.c
+ *   \brief Struct muncher for making SDNA.
+ *   \ingroup DNA
  *
+ * \section aboutmakesdnac About makesdna tool
  * Originally by Ton, some mods by Frank, and some cleaning and
  * extension by Nzc.
  *
@@ -43,7 +46,7 @@
  * and the offsets for reaching a particular one.
  *
  * There is a facility to get verbose output from sdna. Search for
- * debugSDNA. This int can be set to 0 (no output) to some int. Higher
+ * \ref debugSDNA. This int can be set to 0 (no output) to some int. Higher
  * numbers give more output.
  * */
 
@@ -146,7 +149,8 @@ short **structs, *structdata;	/* at sp= structs[a] is the first address of a str
 								   sp[0] is type number
 								   sp[1] is amount of elements
 								   sp[2] sp[3] is typenr,  namenr (etc) */
-/*
+/**
+ * Variable to control debug output of makesdna.
  * debugSDNA:
  *  - 0 = no output, except errors
  *  - 1 = detail actions
diff --git a/source/blender/makesrna/RNA_documentation.h b/source/blender/makesrna/RNA_documentation.h
index aef1f19bf8b..de8e2336bf2 100644
--- a/source/blender/makesrna/RNA_documentation.h
+++ b/source/blender/makesrna/RNA_documentation.h
@@ -1,4 +1,4 @@
-/*! \page makesrna makesrna
+/** \page makesrna makesrna
  *  \ingroup RNA
  *  \section aboutmakesrna About RNA
  *  The \ref RNA module defines and provides the access API to the data, thus encapsulating \ref DNA