Documentation: Improved public API header file documentation

Modified all the GPL banners, fixed various errors, and added more groupings.
skyjake · Jan 13, 2012 · a558de3 · a558de3
1 parent bf3dee1
commit a558de3
Show file tree

Hide file tree

Showing 30 changed files with 709 additions and 604 deletions.
diff --git a/doomsday/engine/api/dd_animator.h b/doomsday/engine/api/dd_animator.h
@@ -1,34 +1,36 @@
-/**\file
- *\section License
- * License: GPL
- * Online License Link: http://www.gnu.org/licenses/gpl.html
+/**
+ * @file dd_animator.h
+ * Moves a value gradually from a start value to a target value.
+ * @ingroup math
  *
- *\author Copyright © 2003-2010 Jaakko Keränen <jaakko.keranen@iki.fi>
- *\author Copyright © 2006-2010 Daniel Swanson <danij@dengine.net>
+ * The value transition is carried out in a fixed number of steps.
  *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
+ * @authors Copyright © 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2006-2012 Daniel Swanson <danij@dengine.net>
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
  *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin St, Fifth Floor,
- * Boston, MA  02110-1301  USA
+ * <small>This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by the
+ * Free Software Foundation; either version 2 of the License, or (at your
+ * option) any later version. This program is distributed in the hope that it
+ * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+ * Public License for more details. You should have received a copy of the GNU
+ * General Public License along with this program; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
  */
 
 #ifndef LIBDENG_ANIMATOR_H
 #define LIBDENG_ANIMATOR_H
 
+/// @addtogroup math
+///@{
+
 /**
- * Provides a way to gradually move between target values.
- *
- * @ingroup types
+ * Animator instance.
  */
 typedef struct {
     float           value;
@@ -42,8 +44,6 @@ void            Animator_Think(animator_t* v);
 
 /**
  * 2D vector animator.
- *
- * @ingroup types
  */
 typedef animator_t animatorvector2_t[2];
 
@@ -53,8 +53,6 @@ void            AnimatorVector2_Think(animatorvector2_t v);
 
 /**
  * 3D vector animator.
- *
- * @ingroup types.
  */
 typedef animator_t animatorvector3_t[3];
 
@@ -64,13 +62,13 @@ void            AnimatorVector3_Think(animatorvector3_t v);
 
 /**
  * 4D vector animator.
- *
- * @ingroup types.
  */
 typedef animator_t animatorvector4_t[4];
 
 void            AnimatorVector4_Init(animatorvector4_t v, float x, float y, float z, float w);
 void            AnimatorVector4_Set(animatorvector4_t v, float x, float y, float z, float w, int steps);
 void            AnimatorVector4_Think(animatorvector4_t v);
 
+///@}
+
 #endif /* LIBDENG_ANIMATOR_H */
diff --git a/doomsday/engine/api/dd_fontrenderer.h b/doomsday/engine/api/dd_fontrenderer.h
@@ -1,36 +1,30 @@
-/**\file dd_fontrenderer.h
- *\section License
- * License: GPL
- * Online License Link: http://www.gnu.org/licenses/gpl.html
+/**
+ * @file dd_fontrenderer.h
+ * Font renderer.
  *
- *\author Copyright © 1999-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
- *\author Copyright © 2006-2012 Daniel Swanson <danij@dengine.net>
+ * @ingroup gl
  *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
+ * @authors Copyright © 1999-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2006-2012 Daniel Swanson <danij@dengine.net>
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
  *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin St, Fifth Floor,
- * Boston, MA  02110-1301  USA
- */
-
-/**
- * Font Renderer.
+ * <small>This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by the
+ * Free Software Foundation; either version 2 of the License, or (at your
+ * option) any later version. This program is distributed in the hope that it
+ * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+ * Public License for more details. You should have received a copy of the GNU
+ * General Public License along with this program; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
  */
 
 #ifndef LIBDENG_API_FONT_RENDERER_H
 #define LIBDENG_API_FONT_RENDERER_H
 
-//#include "doomsday.h"
-
 /**
  * Font attributes are managed as a finite stack of attribute sets.
  * This value defines the maximum allowed depth of the attribute stack.

diff --git a/doomsday/engine/api/dd_gl.h b/doomsday/engine/api/dd_gl.h
@@ -1,37 +1,38 @@
-/**\file dd_gl.h
- *\section License
- * License: GPL
- * Online License Link: http://www.gnu.org/licenses/gpl.html
+/**
+ * @file dd_gl.h
+ * Doomsday graphics library.
  *
- *\author Copyright © 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
- *\author Copyright © 2007-2012 Daniel Swanson <danij@dengine.net>
- *\author Copyright © 2006 Jamie Jones <jamie_jones_au@yahoo.com.au>
+ * @ingroup gl
  *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
+ * @authors Copyright © 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2007-2012 Daniel Swanson <danij@dengine.net>
+ * @authors Copyright © 2006 Jamie Jones <jamie_jones_au@yahoo.com.au>
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
  *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin St, Fifth Floor,
- * Boston, MA  02110-1301  USA
- */
-
-/**
- * Doomsday graphics library.
+ * <small>This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by the
+ * Free Software Foundation; either version 2 of the License, or (at your
+ * option) any later version. This program is distributed in the hope that it
+ * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+ * Public License for more details. You should have received a copy of the GNU
+ * General Public License along with this program; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
  */
 
 #ifndef LIBDENG_DGL_H
 #define LIBDENG_DGL_H
 
 #include "rect.h"
 
+/**
+ * @defgroup gl Graphics Library
+ */
+///@{
+
 enum {
     // Values
     DGL_SCISSOR_BOX,
@@ -102,7 +103,7 @@ typedef int DGLsizei;
 typedef double DGLdouble;
 typedef unsigned int DGLenum;
 
-// Texture formats:
+/// Texture formats.
 typedef enum dgltexformat_e {
     DGL_RGB,
     DGL_RGBA,
@@ -112,6 +113,7 @@ typedef enum dgltexformat_e {
     DGL_LUMINANCE_PLUS_A8
 } dgltexformat_t;
 
+/// Primitive types.
 typedef enum dglprimtype_e {
     DGL_LINES,
     DGL_TRIANGLES,
@@ -124,6 +126,7 @@ typedef enum dglprimtype_e {
 
 #define DDNUM_BLENDMODES    9
 
+/// Blending modes.
 typedef enum blendmode_e {
     BM_ZEROALPHA = -1,
     BM_NORMAL,
@@ -140,7 +143,7 @@ typedef enum blendmode_e {
 #define VALID_BLENDMODE(val) ((val) >= BM_ZEROALPHA && (val) <= BM_ALPHA_SUBTRACT)
 
 typedef struct dgl_vertex_s {
-    float           xyz[4]; // The fourth is padding.
+    float           xyz[4]; ///< The fourth is padding.
 } dgl_vertex_t;
 
 typedef struct dgl_texcoord_s {
@@ -159,26 +162,26 @@ typedef struct {
     DGLubyte        rgba[4];
 } dgl_rgba_t;
 
-// A 2-vertex with texture coordinates, using floats
+/// 2-vertex with texture coordinates, using floats.
 typedef struct {
     float           pos[2];
     float           tex[2];
 } dgl_ft2vertex_t;
 
-// A 3-vertex with texture coordinates, using floats
+/// 3-vertex with texture coordinates, using floats.
 typedef struct {
     float           pos[3];
     float           tex[2];
 } dgl_ft3vertex_t;
 
-// A 3-vertex with texture coordinates and a color, using floats
+/// 3-vertex with texture coordinates and a color, using floats.
 typedef struct {
     float           pos[3];
     float           tex[2];
     float           color[4];
 } dgl_fct3vertex_t;
 
-// A colored 3-vertex, using floats
+/// Colored 3-vertex, using floats.
 typedef struct {
     float           pos[3];
     float           color[4];
@@ -266,4 +269,6 @@ DGLuint DGL_NewTextureWithParams(dgltexformat_t format, int width, int height,
 int             DGL_Bind(DGLuint texture);
 void            DGL_DeleteTextures(int num, const DGLuint* names);
 
+///@}
+
 #endif /* LIBDENG_DGL_H */
diff --git a/doomsday/engine/api/dd_infine.h b/doomsday/engine/api/dd_infine.h
@@ -1,46 +1,47 @@
-/**\file dd_infine.h
- *\section License
- * License: GPL
- * Online License Link: http://www.gnu.org/licenses/gpl.html
+/**
+ * @file dd_infine.h
+ * Interactive animation sequence system.
  *
- *\author Copyright © 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
- *\author Copyright © 2006-2012 Daniel Swanson <danij@dengine.net>
+ * @ingroup infine
  *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
+ * @authors Copyright © 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2006-2012 Daniel Swanson <danij@dengine.net>
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
  *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin St, Fifth Floor,
- * Boston, MA  02110-1301  USA
+ * <small>This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by the
+ * Free Software Foundation; either version 2 of the License, or (at your
+ * option) any later version. This program is distributed in the hope that it
+ * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+ * Public License for more details. You should have received a copy of the GNU
+ * General Public License along with this program; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
  */
 
 #ifndef LIBDENG_API_INFINE_H
 #define LIBDENG_API_INFINE_H
 
 /**
- * @defgroup infine InFine System
- *
- * The "In Fine" finale sequence system.
+ * @defgroup infine Finale Animations
+ * @ingroup gui
+ * The "In Fine" finale interactive animation sequence system.
  */
+///@{
 
 /// Finale identifier. Used throughout the public API when referencing active Finales.
 typedef ident_t finaleid_t;
 
 /**
  * @defgroup finaleFlags Finale Flags
- * @ingroup apiFlags
+ * @ingroup infine apiFlags
  */
-/*@{*/
+///@{
 #define FF_LOCAL            0x1 /// Local scripts are executed client-side.
-/*@}*/
+///@}
 
 /**
  * Execute a set of Finale commands.
@@ -100,4 +101,6 @@ boolean FI_ScriptIsMenuTrigger(finaleid_t id);
 
 int FI_ScriptResponder(finaleid_t id, const void* ev);
 
+///@}
+
 #endif /* LIBDENG_API_INFINE_H */