Documentation: Various improvements

doomsday/engine/portable/include/library.h

@@ -102,6 +102,7 @@ const char* Library_Type(const Library* lib);
 /**
  * Looks up a symbol from the library.
  *
+ * @param lib         Library instance.
  * @param symbolName  Name of the symbol.
  *
  * @return @c NULL if the symbol is not defined. Otherwise the address of

doomsday/engine/portable/include/nativeui.h

@@ -39,9 +39,9 @@ typedef enum {
 /**
  * Shows a native modal message dialog.
  *
- * @param type   Type of the dialog (which icon to show).
- * @param title  Title for the dialog.
- * @param msg    Message.
+ * @param type         Type of the dialog (which icon to show).
+ * @param title        Title for the dialog.
+ * @param msg          Message.
  * @param detailedMsg  Optional, possibly long extra content to show. Can be @c NULL.
  */
 void Sys_MessageBox(messageboxtype_t type, const char* title, const char* msg, const char* detailedMsg);
@@ -59,9 +59,11 @@ int Sys_MessageBoxWithButtons(messageboxtype_t type, const char* title, const ch
 /**
  * Shows a native modal message dialog. The "more detail" content is read from a file.
  *
- * @param type   Type of the dialog (which icon to show).
- * @param title  Title for the dialog.
- * @param msg    Message.
+ * @param type             Type of the dialog (which icon to show).
+ * @param title            Title for the dialog.
+ * @param msg              Message.
+ * @param informativeMsg   Additional information to show under the message
+ *                         (perhaps using a smaller font).
  * @param detailsFileName  Name of the file where to read details.
  */
 void Sys_MessageBoxWithDetailsFromFile(messageboxtype_t type, const char* title, const char* msg,

doomsday/engine/portable/src/dd_main.cpp

@@ -581,8 +581,8 @@ static bool parsePathLumpMapping(lumpname_t lumpName, ddstring_t* path, char con
 }
 
 /**
- * <pre>LUMPNAM0 \Path\In\The\Base.ext
- * LUMPNAM1 Path\In\The\RuntimeDir.ext
+ * <pre> LUMPNAM0 \\Path\\In\\The\\Base.ext
+ * LUMPNAM1 Path\\In\\The\\RuntimeDir.ext
  *  :</pre>
  */
 static bool parsePathLumpMappings(char const* buffer)
@@ -1182,7 +1182,7 @@ bool DD_ChangeGame(de::Game& game, bool allowReload = false)
             DD_SetActivePluginId(0);
         }
 
-        /// @kludge Use more appropriate task names when unloading a game.
+        /// @todo Kludge: Use more appropriate task names when unloading a game.
         if(isNullGame(game))
         {
             gameChangeTasks[0].name = "Unloading game...";

doomsday/engine/portable/src/net_main.c

@@ -240,7 +240,7 @@ void Net_SendBuffer(int toPlayer, int spFlags)
 }
 
 /**
- * @return         @C false, if there are no packets waiting.
+ * @return @c false, if there are no packets waiting.
  */
 boolean Net_GetPacket(void)
 {

doomsday/libdeng2/include/de/filesys/fs.h

@@ -29,7 +29,13 @@
  * @defgroup fs File System
  *
  * The file system (de::FS) governs a tree of files and folders, and provides
- * the means to access all data in libdeng2.
+ * the means to access all data in libdeng2. It follows the metaphor of a UNIX
+ * file system, where not all files are "regular" files, but instead may
+ * represent non-file objects that still support serialization into byte arrays
+ * or have a byte-stream input/output interface. This way it provides a uniform
+ * interface to all public data that is compatible with network communications,
+ * persistence, hierarchical organization and lookup, item metadata (names,
+ * modification timestamps, custom key/values) and scripting.
  *
  * To facilitate efficient O(log n) searches over the entire file system,
  * de::FS maintains an index of all files and folders by name. There is

doomsday/libdeng2/include/de/filesys/libraryfile.h

@@ -27,9 +27,10 @@ namespace de
     class Library;
 
     /**
-     * Provides a way to load a shared library. The Library will be loaded
-     * automatically when someone attempts to use it. Unloading the library occurs when
-     * the LibraryFile instance is deleted, or when unload() is called.
+     * Provides a way to load and unload a shared library. The Library will be
+     * loaded automatically when someone attempts to use it. Unloading the
+     * library occurs when the LibraryFile instance is deleted, or when
+     * unload() is called.
      *
      * @see Library
      *
@@ -76,7 +77,10 @@ namespace de
         void clear();
 
         /**
-         * Checks whether the name of the library file matches.
+         * Checks whether the name of the library file matches. An "underscore
+         * name" is a convention used for some plugins where the name of the
+         * plugin is prefixed by, e.g., "audio_". The "underscore name" is the
+         * part of the file that follows the underscore.
          *
          * @param nameAfterUnderscore  Part of the name following underscore.
          */

doomsday/libdeng2/src/filesys/file.cpp

@@ -192,6 +192,7 @@ void File::set(Offset /*at*/, const Byte* /*values*/, Size /*count*/)
 
 File::Accessor::Accessor(File& owner, Property prop) : _owner(owner), _prop(prop)
 {
+    /// @todo Accessor should listen for deletion of the owner file.
     update();
 }