From a558de3dc500444f5e5f24da2180eb7e7b0fd747 Mon Sep 17 00:00:00 2001 From: skyjake Date: Fri, 13 Jan 2012 18:19:55 +0200 Subject: [PATCH] Documentation: Improved public API header file documentation Modified all the GPL banners, fixed various errors, and added more groupings. --- doomsday/engine/api/dd_animator.h | 52 ++++---- doomsday/engine/api/dd_fontrenderer.h | 42 +++--- doomsday/engine/api/dd_gl.h | 63 +++++---- doomsday/engine/api/dd_infine.h | 51 +++---- doomsday/engine/api/dd_plugin.h | 98 ++++++++------ doomsday/engine/api/dd_string.h | 72 +++++----- doomsday/engine/api/dd_types.h | 42 +++--- doomsday/engine/api/dd_ui.h | 42 +++--- doomsday/engine/api/dd_vectorgraphic.h | 45 +++---- doomsday/engine/api/dd_wad.h | 48 +++---- doomsday/engine/api/dd_world.h | 68 ++++++---- doomsday/engine/api/dengproject.h | 35 +++-- doomsday/engine/api/dfile.h | 47 ++++--- doomsday/engine/api/doomsday.h | 15 ++- doomsday/engine/api/materialarchive.h | 54 +++++--- doomsday/engine/api/point.h | 57 ++++---- doomsday/engine/api/rect.h | 34 +++-- doomsday/engine/api/size.h | 34 +++-- doomsday/engine/api/smoother.h | 63 +++++---- doomsday/engine/api/stringpool.h | 47 +++---- doomsday/engine/api/sys_audiod.h | 47 +++---- doomsday/engine/api/sys_audiod_mus.h | 57 ++++---- doomsday/engine/api/sys_audiod_sfx.h | 126 +++++++++--------- doomsday/engine/api/uri.h | 42 ++++-- doomsday/engine/doxygen.css | 3 + doomsday/engine/engine.pro | 1 + .../engine/portable/include/pathdirectory.h | 19 +-- doomsday/plugins/jdoom/doxygen.css | 3 + doomsday/plugins/jheretic/doxygen.css | 3 + doomsday/plugins/jhexen/doxygen.css | 3 + 30 files changed, 709 insertions(+), 604 deletions(-) diff --git a/doomsday/engine/api/dd_animator.h b/doomsday/engine/api/dd_animator.h index 81ba043a4c..8601154e8b 100644 --- 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 - *\author Copyright © 2006-2010 Daniel Swanson + * 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 + * @authors Copyright © 2006-2012 Daniel Swanson * - * 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 + * 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 */ #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,8 +62,6 @@ void AnimatorVector3_Think(animatorvector3_t v); /** * 4D vector animator. - * - * @ingroup types. */ typedef animator_t animatorvector4_t[4]; @@ -73,4 +69,6 @@ void AnimatorVector4_Init(animatorvector4_t v, float x, float y, floa 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 index 5ce1e2f9e5..55231951ac 100644 --- 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 - *\author Copyright © 2006-2012 Daniel Swanson + * @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 + * @authors Copyright © 2006-2012 Daniel Swanson * - * 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. + * 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 */ #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 index 943fe49fee..cff4baa2e9 100644 --- a/doomsday/engine/api/dd_gl.h +++ b/doomsday/engine/api/dd_gl.h @@ -1,30 +1,26 @@ -/**\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 - *\author Copyright © 2007-2012 Daniel Swanson - *\author Copyright © 2006 Jamie Jones + * @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 + * @authors Copyright © 2007-2012 Daniel Swanson + * @authors Copyright © 2006 Jamie Jones * - * 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. + * 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 */ #ifndef LIBDENG_DGL_H @@ -32,6 +28,11 @@ #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 index 114d1ac87f..c8bf86a7ed 100644 --- 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 - *\author Copyright © 2006-2012 Daniel Swanson + * @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 + * @authors Copyright © 2006-2012 Daniel Swanson * - * 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 + * 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 */ #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 */ diff --git a/doomsday/engine/api/dd_plugin.h b/doomsday/engine/api/dd_plugin.h index ec288589ca..cdba0e42b7 100644 --- a/doomsday/engine/api/dd_plugin.h +++ b/doomsday/engine/api/dd_plugin.h @@ -1,34 +1,35 @@ -/**\file dd_plugin.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html - * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2006-2012 Daniel Swanson +/** + * @file dd_plugin.h + * Plugin subsystem. + * @ingroup base * - * 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 + * @authors Copyright © 2006-2012 Daniel Swanson * - * 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 - */ - -/** - * Plugin Subsystem. + * 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 */ #ifndef LIBDENG_PLUGIN_H #define LIBDENG_PLUGIN_H +/** + * @defgroup plugin Plugins + * @ingroup base + */ +///@{ + #include "../portable/include/dd_version.h" #define LIBDENG_PLUGINDESC "(" DOOMSDAY_NICENAME " Plugin)" @@ -39,63 +40,74 @@ typedef int (*pluginfunc_t) (void); typedef int (*hookfunc_t) (int type, int parm, void *data); -// Hook types. +/// Hook types. enum { - HOOK_STARTUP = 0, // Called ASAP after startup. - HOOK_INIT = 1, // Called after engine has been initialized. - HOOK_DEFS = 2, // Called after DEDs have been loaded. - HOOK_MAP_CONVERT = 3, // Called when a map needs converting. - HOOK_TICKER = 4, // Called as part of the run loop. - HOOK_DEMO_STOP = 5, // Called when demo playback completes. - HOOK_FINALE_SCRIPT_BEGIN = 6, // Called as a script begins. - HOOK_FINALE_SCRIPT_STOP = 7, // Called as a script stops. - HOOK_FINALE_SCRIPT_TICKER = 8, // Called each time a script 'thinks'. - HOOK_FINALE_EVAL_IF = 9, // Called to evaluate an IF conditional statement. - HOOK_VIEWPORT_RESHAPE = 10, // Called when viewport dimensions change. + HOOK_STARTUP = 0, ///< Called ASAP after startup. + HOOK_INIT = 1, ///< Called after engine has been initialized. + HOOK_DEFS = 2, ///< Called after DEDs have been loaded. + HOOK_MAP_CONVERT = 3, ///< Called when a map needs converting. + HOOK_TICKER = 4, ///< Called as part of the run loop. + HOOK_DEMO_STOP = 5, ///< Called when demo playback completes. + HOOK_FINALE_SCRIPT_BEGIN = 6, ///< Called as a script begins. + HOOK_FINALE_SCRIPT_STOP = 7, ///< Called as a script stops. + HOOK_FINALE_SCRIPT_TICKER = 8, ///< Called each time a script 'thinks'. + HOOK_FINALE_EVAL_IF = 9, ///< Called to evaluate an IF conditional statement. + HOOK_VIEWPORT_RESHAPE = 10, ///< Called when viewport dimensions change. NUM_HOOK_TYPES }; /// Unique identifier attributed to each plugin during initial startup. typedef int pluginid_t; -// Paramaters for HOOK_FINALE_EVAL_IF +/// Paramaters for HOOK_FINALE_EVAL_IF typedef struct { const char* token; boolean returnVal; } ddhook_finale_script_evalif_paramaters_t; -// Paramaters for HOOK_FINALE_SCRIPT_TICKER +/// Paramaters for HOOK_FINALE_SCRIPT_TICKER typedef struct { boolean runTick; boolean canSkip; } ddhook_finale_script_ticker_paramaters_t; -// Paramaters for HOOK_VIEWPORT_RESHAPE +/// Paramaters for HOOK_VIEWPORT_RESHAPE typedef struct { RectRaw geometry; // New/Current. RectRaw oldGeometry; // Previous. } ddhook_viewport_reshape_t; /** - * This routine is called by plugins who want to register hooks. + * Registers a new hook function. + * A plugin should call this to add a hook function to be executed at the time + * specified by @a hook_type. + * + * @param hook_type Hook type. + * @param hook Pointer to hook function. * * @return @c true, iff the hook was successfully registered. */ int Plug_AddHook(int hook_type, hookfunc_t hook); /** - * Removes the given hook. + * Removes @a hook from the registered hook functions. + * + * @param hook_type Hook type. + * @param hook Pointer to hook function. * * @return @c true iff it was found. */ int Plug_RemoveHook(int hook_type, hookfunc_t hook); /** - * Check if a plugin is available of the specified type. + * Check if there are any hooks of type @a hookType registered. + * + * @param hookType Type of hook to check for. * - * @param hookType Type of hook to check we have a plugin for. - * @return @c true, if a plugin is available for this hook type. + * @return @c true, if one or more hooks are available for type @a hookType. */ int Plug_CheckForHook(int hookType); +///@} + #endif /* LIBDENG_PLUGIN_H */ diff --git a/doomsday/engine/api/dd_string.h b/doomsday/engine/api/dd_string.h index ef757a59ae..b4d80ade50 100644 --- a/doomsday/engine/api/dd_string.h +++ b/doomsday/engine/api/dd_string.h @@ -1,25 +1,36 @@ -/**\file - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file dd_string.h + * Dynamic text string. + * + * Simple dynamic string management. @ingroup base + * + * Uses @ref memzone or standard malloc for memory allocation, chosen during + * initialization of a string. The string itself is always allocated with + * malloc. The @ref memzone is not thread-safe. * - *\author Copyright © 2003-2010 Jaakko Keränen - *\author Copyright © 2008-2010 Daniel Swanson + * @todo Rename to Str? (str.h) + * @todo AutoStr for automatically garbage-collected strings (good for return values, + * temporary variables when printing). + * @todo Make this opaque for better forward compatibility -- prevents initialization + * with static C strings, though (which is probably for the better anyway). + * @todo Derive from Qt::QString * - * 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-2010 Jaakko Keränen + * @authors Copyright © 2008-2010 Daniel Swanson * - * 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 + * 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 */ #ifndef LIBDENG_API_STRING_H @@ -30,22 +41,15 @@ #include "writer.h" /** - * Dynamic String. Simple dynamic string management. - * - * You can init with static string constants, for example: - * ddstring_t mystr = { "Hello world." }; - * - * \note Uses de::Zone or standard malloc for memory allocation, chosen during - * initialization of a string. The string itself is always allocated with - * malloc. The Zone is not thread-safe. + * Dynamic string instance. Use Str_New() to allocate one from the heap, or + * Str_Init() to initialize a string located on the stack. * - * \todo Derive from Qt::QString - * \todo Make this opaque for better forward compatibility -- prevents initialization - * with static C strings, though. + * You can init global ddstring_t variables with static string constants, + * for example: @code ddstring_t mystr = { "Hello world." }; @endcode */ typedef struct ddstring_s { /// String buffer. - char* str; + char* str; /// String length (no terminating nulls). size_t length; @@ -53,10 +57,10 @@ typedef struct ddstring_s { /// Allocated buffer size (note: not necessarily equal to ddstring_t::length). size_t size; - // Memory management. - void (*memFree)(void*); - void* (*memAlloc)(size_t n); - void* (*memCalloc)(size_t n); + // Memory management. + void (*memFree)(void*); + void* (*memAlloc)(size_t n); + void* (*memCalloc)(size_t n); } ddstring_t; // Format checking for Str_Appendf in GCC2 diff --git a/doomsday/engine/api/dd_types.h b/doomsday/engine/api/dd_types.h index 4cd8a05e18..47f3a7f6c0 100644 --- a/doomsday/engine/api/dd_types.h +++ b/doomsday/engine/api/dd_types.h @@ -1,30 +1,26 @@ -/**\file dd_types.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file dd_types.h + * Type definitions. * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2007-2012 Daniel Swanson - *\author Copyright © 2006-2008 Jamie Jones + * @ingroup base * - * 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 + * @authors Copyright © 2007-2012 Daniel Swanson + * @authors Copyright © 2006-2008 Jamie Jones * - * 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 - */ - -/** - * Type Definitions + * 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 */ #ifndef LIBDENG_TYPES_H diff --git a/doomsday/engine/api/dd_ui.h b/doomsday/engine/api/dd_ui.h index e358d7a177..a9976083d1 100644 --- a/doomsday/engine/api/dd_ui.h +++ b/doomsday/engine/api/dd_ui.h @@ -1,33 +1,35 @@ -/**\file dd_ui.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file dd_ui.h + * User interface. + * @ingroup gui * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2005-2012 Daniel Swanson + * @todo The meaning of the "fi_" prefix is unclear; rename to "ui_"? * - * 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 + * @authors Copyright © 2005-2012 Daniel Swanson * - * 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 + * 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 */ #ifndef LIBDENG_API_GUI_H #define LIBDENG_API_GUI_H /** - * @defgroup gui GUI System + * @defgroup gui GUI */ +///@{ /// Numeric identifiers of predefined colors. enum { @@ -296,4 +298,6 @@ void FIData_TextSetColorAndAlpha(struct fi_object_s* text, float red, float gree */ size_t FIData_TextLength(struct fi_object_s* text); +///@} + #endif /* LIBDENG_API_GUI_H */ diff --git a/doomsday/engine/api/dd_vectorgraphic.h b/doomsday/engine/api/dd_vectorgraphic.h index 49300c3cf3..8dbc2c73c1 100644 --- a/doomsday/engine/api/dd_vectorgraphic.h +++ b/doomsday/engine/api/dd_vectorgraphic.h @@ -1,34 +1,31 @@ -/**\file dd_vectorgraphic.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html - * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2006-2012 Daniel Swanson +/** + * @file dd_vectorgraphic.h + * Scalable Vector Graphics (SVG). @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 + * @authors Copyright © 2006-2012 Daniel Swanson * - * 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 - */ - -/** - * SVG (Scalable Vector Graphic). + * 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 */ #ifndef LIBDENG_API_VECTORGRAPHIC_H #define LIBDENG_API_VECTORGRAPHIC_H +/// @addtogroup gl +///@{ + typedef uint32_t svgid_t; #include "point.h" @@ -43,4 +40,6 @@ void GL_DrawSvg(svgid_t svgId, const Point2Rawf* origin); void GL_DrawSvg2(svgid_t svgId, const Point2Rawf* origin, float scale); void GL_DrawSvg3(svgid_t svgId, const Point2Rawf* origin, float scale, float angle); +///@} + #endif /* LIBDENG_API_VECTORGRAPHIC_H */ diff --git a/doomsday/engine/api/dd_wad.h b/doomsday/engine/api/dd_wad.h index 05bfed60b4..4d7cbbe9ed 100644 --- a/doomsday/engine/api/dd_wad.h +++ b/doomsday/engine/api/dd_wad.h @@ -1,35 +1,35 @@ -/**\file dd_wad.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file dd_wad.h + * Wrapper API for accessing data stored in DOOM WAD files. * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2006-2012 Daniel Swanson - *\author Copyright © 1993-1996 by id Software, Inc. + * All data is read through Doomsday's virtual file system (see @ref fs). + * @ingroup resource * - * 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 + * @authors Copyright © 2006-2012 Daniel Swanson + * @authors Copyright © 1993-1996 by id Software, Inc. * - * 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 - */ - -/** - * Implements DOOM's WAD interface as a wrapper to the virtual file system. + * 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 */ #ifndef LIBDENG_API_WAD_H #define LIBDENG_API_WAD_H +/// @addtogroup resource +///@{ + #ifdef __cplusplus extern "C" { #endif @@ -104,4 +104,6 @@ void W_CacheChangeTag(lumpnum_t lumpNum, int tag); } // extern "C" #endif +///@} + #endif /* LIBDENG_API_WAD_H */ diff --git a/doomsday/engine/api/dd_world.h b/doomsday/engine/api/dd_world.h index a004f4f51d..afb5166d5f 100644 --- a/doomsday/engine/api/dd_world.h +++ b/doomsday/engine/api/dd_world.h @@ -1,30 +1,28 @@ -/**\file - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file dd_world.h + * World Data. * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2006-2012 Daniel Swanson + * World data comprises the map and all the objects in it. The public API + * includes accessing and modifying map data objects via DMU. * - * 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. + * @ingroup map * - * 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. + * @authors Copyright © 2003-2012 Jaakko Keränen + * @authors Copyright © 2006-2012 Daniel Swanson * - * You should have received a copy of the GNU General Public License - * along with this program; if not, see . - */ - -/** - * dd_world.h: Public API to World Data + * @par License + * GPL: http://www.gnu.org/licenses/gpl.html * - * World data comprises the map and all the objects in it. The public API - * includes accessing and modifying map data objects via DMU. + * 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 */ #ifndef __DOOMSDAY_WORLD_H__ @@ -36,6 +34,9 @@ extern "C" { #endif +/// @addtogroup map +///@{ + unsigned int P_ToIndex(const void* ptr); void* P_ToPtr(int type, uint index); int P_Callback(int type, uint index, void* context, @@ -52,6 +53,19 @@ int P_DummyType(void* dummy); boolean P_IsDummy(void* dummy); void* P_DummyExtraData(void* dummy); +uint P_CountGameMapObjs(int identifier); +byte P_GetGMOByte(int identifier, uint elmIdx, int propIdentifier); +short P_GetGMOShort(int identifier, uint elmIdx, int propIdentifier); +int P_GetGMOInt(int identifier, uint elmIdx, int propIdentifier); +fixed_t P_GetGMOFixed(int identifier, uint elmIdx, int propIdentifier); +angle_t P_GetGMOAngle(int identifier, uint elmIdx, int propIdentifier); +float P_GetGMOFloat(int identifier, uint elmIdx, int propIdentifier); + +///@} + +/// @addtogroup dmu +///@{ + /* index-based write functions */ void P_SetBool(int type, uint index, uint prop, boolean param); void P_SetByte(int type, uint index, uint prop, byte param); @@ -120,16 +134,12 @@ void P_GetAnglepv(void* ptr, uint prop, angle_t* params); void P_GetFloatpv(void* ptr, uint prop, float* params); void P_GetPtrpv(void* ptr, uint prop, void* params); -uint P_CountGameMapObjs(int identifier); -byte P_GetGMOByte(int identifier, uint elmIdx, int propIdentifier); -short P_GetGMOShort(int identifier, uint elmIdx, int propIdentifier); -int P_GetGMOInt(int identifier, uint elmIdx, int propIdentifier); -fixed_t P_GetGMOFixed(int identifier, uint elmIdx, int propIdentifier); -angle_t P_GetGMOAngle(int identifier, uint elmIdx, int propIdentifier); -float P_GetGMOFloat(int identifier, uint elmIdx, int propIdentifier); +///@} #ifdef __cplusplus } // extern "C" #endif +///@} + #endif // __DOOMSDAY_WORLD_H__ diff --git a/doomsday/engine/api/dengproject.h b/doomsday/engine/api/dengproject.h index ceb63fbeed..58b2a9c1c2 100644 --- a/doomsday/engine/api/dengproject.h +++ b/doomsday/engine/api/dengproject.h @@ -1,24 +1,23 @@ -/**\file - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file dengproject.h + * General project related definitions. * - *\author Copyright © 2010 Daniel Swanson + * @authors Copyright © 2010-2012 Daniel Swanson + * @authors Copyright © 2012 Jaakko Keränen * - * 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. + * @par License + * GPL: http://www.gnu.org/licenses/gpl.html * - * 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 + * 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 */ #ifndef DENGPROJECT_H diff --git a/doomsday/engine/api/dfile.h b/doomsday/engine/api/dfile.h index 24b19bc1df..e9265280c9 100644 --- a/doomsday/engine/api/dfile.h +++ b/doomsday/engine/api/dfile.h @@ -1,24 +1,24 @@ -/**\file dfile.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file dfile.h + * Unique file reference in the engine's virtual file system. * - *\author Copyright © 2012 Daniel Swanson + * @ingroup fs * - * 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 © 2012 Daniel Swanson * - * 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 + * 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 */ #ifndef LIBDENG_FILESYS_FILEHANDLE_H @@ -30,13 +30,14 @@ extern "C" { #include "dd_types.h" +/// @addtogroup fs +///@{ + +struct dfile_s; // The file handle instance (opaque). + /** - * DFile. DFile Represents a unique (public) file reference in the - * engine's Virtual File System (vfs). - * - * @ingroup fs + * DFile instance. */ -struct dfile_s; // The file handle instance (opaque). typedef struct dfile_s DFile; /** @@ -92,4 +93,6 @@ void DFile_Print(const DFile* file); } // extern "C" #endif +///@} + #endif /* LIBDENG_FILESYS_FILEHANDLE_H */ diff --git a/doomsday/engine/api/doomsday.h b/doomsday/engine/api/doomsday.h index 846e5856e0..8a3fa4ae81 100644 --- a/doomsday/engine/api/doomsday.h +++ b/doomsday/engine/api/doomsday.h @@ -25,8 +25,17 @@ * @mainpage libdeng API * * This documentation covers all the functions and data that Doomsday makes - * available for games and other plugins. The documentation has been organized - * into module (see Modules). + * available for games and other plugins. + * + * @section Overview + * The documentation has been organized into modules. + * The primary ones are listed below: + * - @ref base + * - @ref console + * - @ref input + * - @ref network + * - @ref resource + * - @ref gl */ #ifndef LIBDENG_EXPORTS_H @@ -271,7 +280,7 @@ void Con_SetPrintFilter(con_textfilter_t filter); /** * @defgroup system System Routines - * Functionality provided by the operating system. + * Functionality provided by or related to the operating system. */ ///@{ void Sys_TicksPerSecond(float num); diff --git a/doomsday/engine/api/materialarchive.h b/doomsday/engine/api/materialarchive.h index 69937530e8..ea8262c4d0 100644 --- a/doomsday/engine/api/materialarchive.h +++ b/doomsday/engine/api/materialarchive.h @@ -1,25 +1,25 @@ -/**\file materialarchive.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file materialarchive.h + * Collection of identifier-material pairs. @ingroup resource * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2005-2012 Daniel Swanson + * Used when saving map state (savegames) or sharing world changes with clients. * - * 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 + * @authors Copyright © 2005-2012 Daniel Swanson * - * 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 + * 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 */ #ifndef LIBDENG_MATERIALARCHIVE_H @@ -35,6 +35,10 @@ extern "C" { struct material_s; struct materialarchive_s; + +/** + * MaterialArchive instance. + */ typedef struct materialarchive_s MaterialArchive; typedef unsigned short materialarchive_serialid_t; @@ -63,17 +67,31 @@ struct material_s* MaterialArchive_Find(MaterialArchive* arc, materialarchive_se /** * Returns the number of materials in the archive. + * + * @param arc MaterialArchive instance. */ size_t MaterialArchive_Count(MaterialArchive* arc); +/** + * Serializes the state of the archive using @a writer. + * + * @param arc MaterialArchive instance. + * @param writer Writer instance. + */ void MaterialArchive_Write(MaterialArchive* arc, Writer* writer); /** + * Deserializes the state of the archive from @a reader. + * + * @param arc MaterialArchive instance. * @param forcedVersion Version to interpret as, not actual format version. Use -1 to use whatever * version is encountered. + * @param reader Reader instance. */ void MaterialArchive_Read(MaterialArchive* arc, int forcedVersion, Reader* reader); +///@} + #ifdef __cplusplus } #endif diff --git a/doomsday/engine/api/point.h b/doomsday/engine/api/point.h index 41c1bf3dbd..4361455f76 100644 --- a/doomsday/engine/api/point.h +++ b/doomsday/engine/api/point.h @@ -1,24 +1,22 @@ -/**\file point.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html - * - *\author Copyright © 2012 Daniel Swanson +/** + * @file point.h + * 2D points. @ingroup math * - * 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 © 2012 Daniel Swanson * - * 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 + * 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 */ #ifndef LIBDENG_DATA_POINT_H @@ -29,9 +27,8 @@ extern "C" { #endif /** - * Point2Raw. Point 2 Raw (integer). Is intended as a handy POD - * structure for easy manipulation of two dimensional plane points, - * with integer precison. + * 2D point with integer values. A handy POD structure for easy manipulation of + * two dimensional plane points. @ingroup math */ typedef struct Point2Raw_s { union { @@ -43,10 +40,12 @@ typedef struct Point2Raw_s { }; } Point2Raw; +struct point2_s; // The Point2f instance (opaque). + /** - * Point2. Class for manipulating 2d plane points using integer precision. + * Point2 instance. Class for manipulating 2D plane points using integer precision. + * Use Point2_New() or one of the other constructors to instantiate. */ -struct point2_s; // The Point2f instance (opaque). typedef struct point2_s Point2; Point2* Point2_New(void); @@ -76,9 +75,9 @@ void Point2_Sum(Point2* point, const Point2* other); boolean Point2_Equality(const Point2* point, const Point2* other); /** - * Point2Rawf. Point 2 Raw (f)loating point. Is intended as a handy POD - * structure for easy manipulation of two dimensional plane points, - * with floating point precison. + * 2D point with floating point values. A handy POD structure for easy + * manipulation of two dimensional plane points. + * @ingroup math */ typedef struct Point2Rawf_s { union { @@ -90,10 +89,12 @@ typedef struct Point2Rawf_s { }; } Point2Rawf; +struct point2f_s; // The Point2f instance (opaque). + /** - * Point2f. Class for manipulating 2d plane points using floating point precision. + * Point2f instance. Class for manipulating 2D plane points using floating-point precision. + * Use Point2f_New() or one of the other constructors to instantiate. */ -struct point2f_s; // The Point2f instance (opaque). typedef struct point2f_s Point2f; Point2f* Point2f_New(void); diff --git a/doomsday/engine/api/rect.h b/doomsday/engine/api/rect.h index e7e1acabad..dc20997a5c 100644 --- a/doomsday/engine/api/rect.h +++ b/doomsday/engine/api/rect.h @@ -1,24 +1,22 @@ -/**\file rect.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html - * - *\author Copyright © 2012 Daniel Swanson +/** + * @file rect.h + * Rectangles. @ingroup math * - * 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 © 2012 Daniel Swanson * - * 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 + * 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 */ #ifndef LIBDENG_DATA_RECT_H diff --git a/doomsday/engine/api/size.h b/doomsday/engine/api/size.h index 6c13ccdac1..153ad13f23 100644 --- a/doomsday/engine/api/size.h +++ b/doomsday/engine/api/size.h @@ -1,24 +1,22 @@ -/**\file size.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html - * - *\author Copyright © 2012 Daniel Swanson +/** + * @file size.h + * 2D sizes. @ingroup math * - * 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 © 2012 Daniel Swanson * - * 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 + * 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 */ #ifndef LIBDENG_DATA_SIZE_H diff --git a/doomsday/engine/api/smoother.h b/doomsday/engine/api/smoother.h index 884a4fa8e7..8f5c95c571 100644 --- a/doomsday/engine/api/smoother.h +++ b/doomsday/engine/api/smoother.h @@ -1,25 +1,26 @@ -/**\file smoother.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file smoother.h + * Interpolator for smoothing out a movement curve. @ingroup math * - *\author Copyright © 2012 Jaakko Keränen - *\author Copyright © 2012 Daniel Swanson + * The original movement path is composed out of discrete 3D points. Smoother + * calculates the points in between. * - * 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 © 2011-2012 Jaakko Keränen + * @authors Copyright © 2012 Daniel Swanson * - * 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 + * 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 */ #ifndef LIBDENG_SMOOTHER_H @@ -32,28 +33,38 @@ extern "C" { #define SMOOTHER_MOVE_EPSILON .001f struct smoother_s; // The smoother instance (opaque). + +/** + * Smoother instance. Use Smoother_New() to construct. + */ typedef struct smoother_s Smoother; /** * Construct a new smoother instance. * - * @return The smoother. + * @return Smoother instance. */ Smoother* Smoother_New(); /** - * Destructs a smoother. This must be called when the smoother is no - * longer needed. + * Destructs a smoother. This must be called when the smoother is no longer + * needed. + * + * @param sm Smoother instance. */ void Smoother_Delete(Smoother* sm); /** - * Resets the smoother instance. + * Resets the smoother instance. More than one discrete input point is needed before + * output values can be calculated again. After calling Smoother_Clear() the state + * of the Smoother is the same as right after construction. + * + * @param sm Smoother instance. */ void Smoother_Clear(Smoother* sm); /** - * Defines a new point in the future of the smoother. + * Defines a new input point in the future of the smoother. * * @param sm Smoother instance. * @param time Point in time (game tick). @@ -72,21 +83,27 @@ void Smoother_AddPos(Smoother* sm, float time, float x, float y, float z, boolea * * @return @c true if the evaluation was successful. When @c false is returned, * the values in @a xyz are not valid. + * + * @see Smoother_Advance() */ boolean Smoother_Evaluate(const Smoother* sm, float* xyz); /** * Determines whether the smoother's Z coordinate is currently on the floor plane. + * @param sm Smoother instance. */ boolean Smoother_IsOnFloor(const Smoother* sm); /** * Determines whether the smoother is currently undergoing movement. + * @param sm Smoother instance. */ boolean Smoother_IsMoving(const Smoother* sm); /** * Advances the smoother @a sm by @a period amount of time. + * @param sm Smoother instance. + * @param period Amount of time to advance the Smoother's current time. */ void Smoother_Advance(Smoother* sm, float period); diff --git a/doomsday/engine/api/stringpool.h b/doomsday/engine/api/stringpool.h index b1c011c0aa..83a0d1a2e1 100644 --- a/doomsday/engine/api/stringpool.h +++ b/doomsday/engine/api/stringpool.h @@ -1,24 +1,27 @@ -/**\file stringpool.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file stringpool.h + * String pool. @ingroup base + * + * Simple data structure for managing a set of unique case-insensitive strings + * with integral interning mechanism. * - *\author Copyright © 2010-2012 Daniel Swanson + * @todo Explain briefly what "interning" means in practice. * - * 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 © 2010-2012 Daniel Swanson * - * 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 + * 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 */ #ifndef LIBDENG_STRINGPOOL_H @@ -30,16 +33,14 @@ extern "C" { #include "dd_types.h" +struct stringpool_s; // The stringpool instance (opaque). + /** - * String Pool. Simple data structure for managing a set of unique case-insensitive - * strings with integral interning mechanism. - * - * @ingroup data + * StringPool instance. Use StringPool_New() or one of the other constructs to create. */ -struct stringpool_s; // The stringpool instance (opaque). typedef struct stringpool_s StringPool; -// Interned string identifier. +/// Interned string identifier. typedef uint StringPoolInternId; /** diff --git a/doomsday/engine/api/sys_audiod.h b/doomsday/engine/api/sys_audiod.h index eb10a68140..7e53b8d171 100644 --- a/doomsday/engine/api/sys_audiod.h +++ b/doomsday/engine/api/sys_audiod.h @@ -1,34 +1,33 @@ -/**\file sys_audiod.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html - * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2006-2012 Daniel Swanson +/** + * @file sys_audiod.h + * Audio driver interface. @ingroup audio * - * 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 + * @authors Copyright © 2006-2012 Daniel Swanson * - * 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 - */ - -/** - * Audio Driver. + * 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 */ #ifndef LIBDENG_AUDIO_DRIVER_H #define LIBDENG_AUDIO_DRIVER_H +/** + * @defgroup audio Audio + */ +///@{ + typedef enum { AUDIOD_DUMMY, AUDIOD_SDL_MIXER, @@ -53,4 +52,6 @@ typedef struct audiodriver_s { int (*Set) (int prop, const void* ptr); } audiodriver_t; +///@} + #endif /* LIBDENG_AUDIO_DRIVER_H */ diff --git a/doomsday/engine/api/sys_audiod_mus.h b/doomsday/engine/api/sys_audiod_mus.h index ffb7273797..e061e89a06 100644 --- a/doomsday/engine/api/sys_audiod_mus.h +++ b/doomsday/engine/api/sys_audiod_mus.h @@ -1,42 +1,39 @@ -/**\file - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html - * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2006-2012 Daniel Swanson +/** + * @file sys_audiod_mus.h + * Music interface for an audio driver. @ingroup audio * - * 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 + * @authors Copyright © 2006-2012 Daniel Swanson * - * 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 - */ - -/** - * sys_audiod_music.h: Audio Driver - Music interfaces. + * 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 */ #ifndef __DOOMSDAY_AUDIO_DRIVER_MUSIC_H__ #define __DOOMSDAY_AUDIO_DRIVER_MUSIC_H__ -// Music interface properties. +/// @addtogroup audio +///@{ + +/// Music interface properties. enum { - MUSIP_ID, // Only for Get()ing. - MUSIP_PLAYING, // Is playback in progress? + MUSIP_ID, ///< Only for Get()ing. + MUSIP_PLAYING, ///< Is playback in progress? MUSIP_VOLUME }; -// Generic driver interface. All other interfaces are based on this. +/// Generic driver interface. All other interfaces are based on this. typedef struct audiointerface_music_generic_s { int (*Init) (void); void (*Shutdown) (void); @@ -47,7 +44,7 @@ typedef struct audiointerface_music_generic_s { void (*Stop) (void); } audiointerface_music_generic_t; -// Driver interface for playing music. +/// Driver interface for playing music. typedef struct audiointerface_music_s { audiointerface_music_generic_t gen; void* (*SongBuffer) (unsigned int length); @@ -55,10 +52,12 @@ typedef struct audiointerface_music_s { int (*PlayFile) (const char *filename, int looped); } audiointerface_music_t; -// Driver interface for playing CD tracks. +/// Driver interface for playing CD tracks. typedef struct audiointerface_cd_s { audiointerface_music_generic_t gen; int (*Play) (int track, int looped); } audiointerface_cd_t; +///@} + #endif diff --git a/doomsday/engine/api/sys_audiod_sfx.h b/doomsday/engine/api/sys_audiod_sfx.h index 6507a2efc5..d156620756 100644 --- a/doomsday/engine/api/sys_audiod_sfx.h +++ b/doomsday/engine/api/sys_audiod_sfx.h @@ -1,101 +1,103 @@ -/**\file - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html - * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2006-2012 Daniel Swanson +/** + * @file sys_audiod_sfx.h + * Sound effects playback interface for an audio driver. @ingroup audio * - * 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 + * @authors Copyright © 2006-2012 Daniel Swanson * - * 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 - */ - -/** - * sys_audiod_sfx.h: Audio driver - SFX interface. + * 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 */ #ifndef __DOOMSDAY_AUDIO_DRIVER_SFX_H__ #define __DOOMSDAY_AUDIO_DRIVER_SFX_H__ -// Sfx Buffer Flags. -#define SFXBF_PLAYING (0x1) // The buffer is playing. -#define SFXBF_3D (0x2) // Otherwise playing in 2D mode. -#define SFXBF_REPEAT (0x4) // Buffer will repeat until stopped. -#define SFXBF_DONT_STOP (0x8) // Never stop until normal finish. -#define SFXBF_RELOAD (0x10000) // Sample must be reloaded before playing. +/// @addtogroup audio +///@{ -// Sfx interface properties. +/** + * @defgroup sfxBufferFlags Sfx Buffer Flags + * @ingroup audio apiFlags + */ +///@{ +#define SFXBF_PLAYING (0x1) ///< The buffer is playing. +#define SFXBF_3D (0x2) ///< Otherwise playing in 2D mode. +#define SFXBF_REPEAT (0x4) ///< Buffer will repeat until stopped. +#define SFXBF_DONT_STOP (0x8) ///< Never stop until normal finish. +#define SFXBF_RELOAD (0x10000) ///< Sample must be reloaded before playing. +///@} + +/// Sfx interface properties. enum { - SFXIP_DISABLE_CHANNEL_REFRESH = 1 // The channel refresh thread is not needed. + SFXIP_DISABLE_CHANNEL_REFRESH = 1 ///< The channel refresh thread is not needed. }; -// Events. +/// Events. enum { - SFXEV_BEGIN, // An update is about to begin. - SFXEV_END // The update is done. + SFXEV_BEGIN, ///< An update is about to begin. + SFXEV_END ///< The update is done. }; -// Buffer properties. +/// Buffer properties. enum { - SFXBP_VOLUME, // 0..1 - SFXBP_FREQUENCY, // 1 = normal - SFXBP_PAN, // -1..1 (2D only) - SFXBP_MIN_DISTANCE, // 3D only + SFXBP_VOLUME, ///< 0..1 + SFXBP_FREQUENCY, ///< 1 = normal + SFXBP_PAN, ///< -1..1 (2D only) + SFXBP_MIN_DISTANCE, ///< 3D only SFXBP_MAX_DISTANCE, SFXBP_POSITION, SFXBP_VELOCITY, SFXBP_RELATIVE_MODE }; -// Listener properties. +/// Listener properties. enum { - SFXLP_UPDATE, // Not a real value (commit deferred) - SFXLP_PRIMARY_FORMAT, // Arguments are bits and rate. + SFXLP_UPDATE, ///< Not a real value (commit deferred) + SFXLP_PRIMARY_FORMAT, ///< Arguments are bits and rate. SFXLP_UNITS_PER_METER, SFXLP_DOPPLER, SFXLP_POSITION, SFXLP_VELOCITY, SFXLP_ORIENTATION, - SFXLP_REVERB // Use SRD_* for indices. + SFXLP_REVERB ///< Use SRD_* for indices. }; typedef struct sfxsample_s { - int id; // Id number of the sound sample. - void* data; // Actual sample data. - unsigned int size; // Size in bytes. - int numSamples; // Number of samples. - int bytesPer; // Bytes per sample (1 or 2). - int rate; // Samples per second. - int group; // Exclusion group (0, if none). + int id; ///< Id number of the sound sample. + void* data; ///< Actual sample data. + unsigned int size; ///< Size in bytes. + int numSamples; ///< Number of samples. + int bytesPer; ///< Bytes per sample (1 or 2). + int rate; ///< Samples per second. + int group; ///< Exclusion group (0, if none). } sfxsample_t; typedef struct sfxbuffer_s { - void* ptr; // Pointer to driver's own buffer object. - void* ptr3D; // Pointer to driver's 3D buffer data. - struct sfxsample_s* sample; // Source sample data. - int bytes; // Bytes per sample (1 or 2). - int rate; // Samples per second. + void* ptr; ///< Pointer to driver's own buffer object. + void* ptr3D; ///< Pointer to driver's 3D buffer data. + struct sfxsample_s* sample; ///< Source sample data. + int bytes; ///< Bytes per sample (1 or 2). + int rate; ///< Samples per second. int flags; - unsigned int length; // Length of the buffer (bytes). - unsigned int cursor; // Write cursor position (%length). - unsigned int written; // Total bytes written. - unsigned int endTime; // System time, milliseconds (if !repeating). - unsigned int freq; // Played samples per second (real freq). + unsigned int length; ///< Length of the buffer (bytes). + unsigned int cursor; ///< Write cursor position (%length). + unsigned int written; ///< Total bytes written. + unsigned int endTime; ///< System time, milliseconds (if !repeating). + unsigned int freq; ///< Played samples per second (real freq). } sfxbuffer_t; -// Generic driver interface. All other interfaces are based on this. +/// Generic driver interface. All other interfaces are based on this. typedef struct audiointerface_sfx_generic_s { int (*Init) (void); sfxbuffer_t* (*Create) (int flags, int bits, int rate); @@ -116,4 +118,6 @@ typedef struct audiointerface_sfx_s { audiointerface_sfx_generic_t gen; } audiointerface_sfx_t; +///@} + #endif diff --git a/doomsday/engine/api/uri.h b/doomsday/engine/api/uri.h index b64614100d..31993e318a 100644 --- a/doomsday/engine/api/uri.h +++ b/doomsday/engine/api/uri.h @@ -1,15 +1,31 @@ -/**\file uri.h - *\section License - * License: GPL - * Online License Link: http://www.trolltech.com/gpl/ +/** + * @file uri.h + * Universal Resource Identifier. + * + * @ingroup base + * + * Convenient interface class designed to assist working with URIs (Universal + * Resource Identifier) to engine-managed resources. This class is based on the + * semantics defined for the QUrl class, a component of the Qt GUI Toolkit. + * + * @todo Derive from Qt::QUrl * - *\author Daniel Swanson - *\author Copyright (C) 1992-2000 Trolltech AS. All rights reserved. + * @authors Daniel Swanson + * @authors Copyright (C) 1992-2000 Trolltech AS. All rights reserved. * - * This class is based on the semantics defined for the QUrl class, a component - * of the Qt GUI Toolkit. + * @par License + * GPL: http://www.gnu.org/licenses/gpl.html * - * \todo Derive from Qt::QUrl + * 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 */ #ifndef LIBDENG_API_URI_H @@ -23,11 +39,11 @@ extern "C" { #include "reader.h" #include "writer.h" +struct uri_s; // The uri instance (opaque). + /** - * Uri: Convenient interface class designed to assist working with URIs - * (Universal Resource Identifier) to engine-managed resources. + * Uri instance. Created with Uri_New() or one of the other constructors. */ -struct uri_s; // The uri instance (opaque). typedef struct uri_s Uri; /// Schemes must be at least this many characters. @@ -54,7 +70,7 @@ Uri* Uri_Copy(Uri* uri, const Uri* other); * compatible path (perhaps base-relative). * * @return Resolved path else @c NULL if non-resolvable. Caller should ensure - * to Str_Delete when no longer needed. + * to Str_Delete() when no longer needed. */ ddstring_t* Uri_Resolved(const Uri* uri); diff --git a/doomsday/engine/doxygen.css b/doomsday/engine/doxygen.css index 3b1ed1d411..5c1a8906b0 100644 --- a/doomsday/engine/doxygen.css +++ b/doomsday/engine/doxygen.css @@ -436,7 +436,10 @@ td.mdescRight p { background-image:url('nav_f.png'); background-repeat:repeat-x; background-color: #E2E8F2; +} +.memdoc dl table td p { + margin: 0; } .memdoc, dl.reflist dd { diff --git a/doomsday/engine/engine.pro b/doomsday/engine/engine.pro index b6e20e013f..d6902b890b 100644 --- a/doomsday/engine/engine.pro +++ b/doomsday/engine/engine.pro @@ -98,6 +98,7 @@ DENG_API_HEADERS = \ api/rect.h \ api/size.h \ api/smoother.h \ + api/stringpool.h \ api/sys_audiod.h \ api/sys_audiod_mus.h \ api/sys_audiod_sfx.h \ diff --git a/doomsday/engine/portable/include/pathdirectory.h b/doomsday/engine/portable/include/pathdirectory.h index 17e96a6460..79e9ed8789 100644 --- a/doomsday/engine/portable/include/pathdirectory.h +++ b/doomsday/engine/portable/include/pathdirectory.h @@ -30,15 +30,16 @@ /** * @defgroup pathComparisonFlags Path Comparison Flags - * @{ + * @ingroup base apiFlags */ -#define PCF_NO_BRANCH 0x1 /// Do not consider branches as possible candidates. -#define PCF_NO_LEAF 0x2 /// Do not consider leaves as possible candidates. -#define PCF_MATCH_PARENT 0x4 /// Only consider nodes whose parent matches that referenced. -#define PCF_MATCH_FULL 0x8 /// Whole path must match completely (i.e., path begins - /// from the same root point) otherwise allow partial - /// (i.e., relative) matches. -/**@}*/ +///@{ +#define PCF_NO_BRANCH 0x1 ///< Do not consider branches as possible candidates. +#define PCF_NO_LEAF 0x2 ///< Do not consider leaves as possible candidates. +#define PCF_MATCH_PARENT 0x4 ///< Only consider nodes whose parent matches that referenced. +#define PCF_MATCH_FULL 0x8 /**< Whole path must match completely (i.e., path begins + from the same root point) otherwise allow partial + (i.e., relative) matches. */ +///@} typedef enum { PT_ANY = -1, @@ -69,7 +70,7 @@ typedef struct pathdirectorynode_s PathDirectoryNode; * Somewhat similar to a Prefix Tree (Trie) representationally although that is * where the similarity ends. * - * @ingroup data + * @ingroup base */ // Number of buckets in the hash table. diff --git a/doomsday/plugins/jdoom/doxygen.css b/doomsday/plugins/jdoom/doxygen.css index 3b1ed1d411..5c1a8906b0 100644 --- a/doomsday/plugins/jdoom/doxygen.css +++ b/doomsday/plugins/jdoom/doxygen.css @@ -436,7 +436,10 @@ td.mdescRight p { background-image:url('nav_f.png'); background-repeat:repeat-x; background-color: #E2E8F2; +} +.memdoc dl table td p { + margin: 0; } .memdoc, dl.reflist dd { diff --git a/doomsday/plugins/jheretic/doxygen.css b/doomsday/plugins/jheretic/doxygen.css index 3b1ed1d411..5c1a8906b0 100644 --- a/doomsday/plugins/jheretic/doxygen.css +++ b/doomsday/plugins/jheretic/doxygen.css @@ -436,7 +436,10 @@ td.mdescRight p { background-image:url('nav_f.png'); background-repeat:repeat-x; background-color: #E2E8F2; +} +.memdoc dl table td p { + margin: 0; } .memdoc, dl.reflist dd { diff --git a/doomsday/plugins/jhexen/doxygen.css b/doomsday/plugins/jhexen/doxygen.css index 3b1ed1d411..5c1a8906b0 100644 --- a/doomsday/plugins/jhexen/doxygen.css +++ b/doomsday/plugins/jhexen/doxygen.css @@ -436,7 +436,10 @@ td.mdescRight p { background-image:url('nav_f.png'); background-repeat:repeat-x; background-color: #E2E8F2; +} +.memdoc dl table td p { + margin: 0; } .memdoc, dl.reflist dd {