Refactor|libcommon: Switched p_inventory.c, p_xg_line.c to C++

doomsday/plugins/common/common.pri

@@ -113,7 +113,7 @@ SOURCES += \
     $$common_src/p_ceiling.cpp \
     $$common_src/p_door.cpp \
     $$common_src/p_floor.cpp \
-    $$common_src/p_inventory.c \
+    $$common_src/p_inventory.cpp \
     $$common_src/p_iterlist.c \
     $$common_src/p_map.cpp \
     $$common_src/p_mapsetup.cpp \
@@ -130,7 +130,7 @@ SOURCES += \
     $$common_src/p_user.c \
     $$common_src/p_view.c \
     $$common_src/p_xgfile.cpp \
-    $$common_src/p_xgline.c \
+    $$common_src/p_xgline.cpp \
     $$common_src/p_xgsave.cpp \
     $$common_src/p_xgsec.c \
     $$common_src/player.cpp \

doomsday/plugins/common/include/p_inventory.h

@@ -1,34 +1,27 @@
-/**\file
- *\section License
- * License: GPL
- * Online License Link: http://www.gnu.org/licenses/gpl.html
+/** @file p_inventory.h  Common code for player inventory.
  *
- *\author Copyright © 2007-2013 Daniel Swanson <danij@dengine.net>
+ * @note The visual representation of the inventory is handled elsewhere.
  *
- * 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 © 2007-2013 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
- */
-
-/**
- * p_inventory.h: Common code for player inventory.
+ * <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>
  */
 
 #if __JHERETIC__ || __JHEXEN__ || __JDOOM64__
-
-#ifndef __COMMON_INVENTORY_H__
-#define __COMMON_INVENTORY_H__
+#ifndef LIBCOMMON_PLAY_INVENTORY_H
+#define LIBCOMMON_PLAY_INVENTORY_H
 
 #include "common.h"
 
@@ -37,20 +30,20 @@
 #define IIF_READY_ALWAYS        0x8 // Item is always "ready" (i.e., usable).
 
 typedef struct {
-    byte            flags;
-    char            niceName[32];
-    char            action[32];
-    char            useSnd[32];
-    char            patch[9];
-    int             hotKeyCtrlIdent;
+    byte flags;
+    char niceName[32];
+    char action[32];
+    char useSnd[32];
+    char patch[9];
+    int hotKeyCtrlIdent;
 } def_invitem_t;
 
 typedef struct {
     inventoryitemtype_t type;
-    textenum_t      niceName;
-    acfnptr_t       action;
-    sfxenum_t       useSnd;
-    patchid_t       patchId;
+    textenum_t niceName;
+    acfnptr_t action;
+    sfxenum_t useSnd;
+    patchid_t patchId;
 } invitem_t;
 
 DENG_EXTERN_C int didUseItem;
@@ -59,29 +52,90 @@ DENG_EXTERN_C int didUseItem;
 extern "C" {
 #endif
 
-void            P_InitInventory(void);
-void            P_ShutdownInventory(void);
+/**
+ * Called during (post-game) init and after updating game/engine state.
+ */
+void P_InitInventory(void);
 
-const invitem_t* P_GetInvItem(int id);
-const def_invitem_t* P_GetInvItemDef(inventoryitemtype_t type);
+/**
+ * Called once, during shutdown.
+ */
+void P_ShutdownInventory(void);
+
+invitem_t const *P_GetInvItem(int id);
 
-void            P_InventoryEmpty(int player);
-int             P_InventoryGive(int player, inventoryitemtype_t type,
-                                int silent);
-int             P_InventoryTake(int player, inventoryitemtype_t type,
-                                int silent);
-int             P_InventoryUse(int player, inventoryitemtype_t type,
-                               int silent);
+def_invitem_t const *P_GetInvItemDef(inventoryitemtype_t type);
 
-int             P_InventorySetReadyItem(int player, inventoryitemtype_t type);
+/**
+ * Should be called only outside of normal play (e.g., when starting a new
+ * game or similar).
+ *
+ * @param player  Player to empty the inventory of.
+ */
+void P_InventoryEmpty(int player);
+
+/**
+ * Give one item of the specified type to the player.
+ *
+ * @param player  Player to give the item to.
+ * @param type    Type of item to give.
+ * @param silent  Non-zero = don't alert the player.
+ *
+ * @return  Non-zero iff an item of the specified type was successfully given to the player.
+ */
+int P_InventoryGive(int player, inventoryitemtype_t type, int silent);
+
+/**
+ * Take one of the specified items from the player (if owned).
+ *
+ * @param player  Player to take the item from.
+ * @param type    Type of item being taken.
+ * @param silent  Non-zero = don't alert the player.
+ *
+ * @return  Non-zero iff an item of the specified type was successfully taken from the player.
+ */
+int P_InventoryTake(int player, inventoryitemtype_t type, int silent);
+
+/**
+ * Attempt to use an item of the specified type.
+ *
+ * @param player  Player using the item.
+ * @param type    The type of item being used ELSE
+ *                IIT_NONE = Ignored.
+ *                NUM_INVENTORYITEM_TYPES = Panic. Use one of everything!!
+ * @param silent  Non-zero - don't alert the player.
+ *
+ * @return  Non-zero iff one (or more) item was successfully used by the player.
+ */
+int P_InventoryUse(int player, inventoryitemtype_t type, int silent);
+
+/**
+ * Attempt to ready an item (or unready a currently readied item).
+ *
+ * @param player  Player to change the ready item of.
+ * @param type    Item type to be readied.
+ *
+ * @return  Non-zero iff successful.
+ */
+int P_InventorySetReadyItem(int player, inventoryitemtype_t type);
+
+/**
+ * Returns the currently readied item, else @c IIT_NONE.
+ */
 inventoryitemtype_t P_InventoryReadyItem(int player);
 
-unsigned int    P_InventoryCount(int player, inventoryitemtype_t type);
+/**
+ * Returns the number of items possessed by the player.
+ *
+ * @param player  Player to check the inventory of.
+ * @param type    Type requirement, limits the count to the specified type.
+ *                @c IIT_NONE= count all.
+ */
+uint P_InventoryCount(int player, inventoryitemtype_t type);
 
 #ifdef __cplusplus
 } // extern "C"
 #endif
 
-#endif
-
-#endif
+#endif // LIBCOMMON_PLAY_INVENTORY_H
+#endif // __JHERETIC__ || __JHEXEN__ || __JDOOM64__

doomsday/plugins/common/include/p_xgline.h

@@ -344,12 +344,16 @@ void XG_Register(void);
 
 // Initialize extended lines for the map.
 void XL_Init(void);
+
 // Called when reseting engine state.
 void XL_Update(void);
 
 void XL_Thinker(void *xlThinkerPtr);
 
-void XL_SetLineType(Line* line, int id);
+/**
+ * Looks for line type definition and sets the line type if one is found.
+ */
+void XL_SetLineType(Line *line, int id);
 
 linetype_t *XL_GetType(int id);
 
@@ -358,22 +362,45 @@ int XL_LineEvent(int evType, int lineType, Line *line, int sideNum, void *data);
 void XL_ActivateLine(dd_bool activating, linetype_t *info, Line *line, int sideNum,
     struct mobj_s *activator, int evType);
 
+/// Function pointer to an XG plane traversal function.
+typedef int (*LineTraverserFunc)(Line *line, dd_bool ceiling/*unused*/, void *context, void *context2, mobj_t *activator);
+
+/**
+ * Executes the specified function on all lines that match the reference
+ * 'rtype'.
+ *
+ * @return  @c false if 'func' returns @c false, otherwise
+ *          @c true. Stops checking when false is returned.
+ */
 int XL_TraverseLines(Line *line, int reftype, int ref, void *context, void *context2,
     struct mobj_s *activator, int (C_DECL *func)());
 
+/// Function pointer to an XG plane traversal function.
+typedef int (*PlaneTraverserFunc)(Sector *sector, dd_bool ceiling, void *context, void *context2, mobj_t *activator);
+
+/**
+ * Executes the specified function on all planes that match the reference
+ * (reftype).
+ *
+ * @return  @c true iff all callbacks return @c true.
+ */
 int XL_TraversePlanes(Line *line, int reftype, int ref, void *context, void *context2,
     dd_bool travSectors, struct mobj_s *activator, int (C_DECL *func)());
 
 // Return false if the event was processed.
 int XL_CrossLine(Line *line, int sideNum, struct mobj_s *thing);
+
 int XL_UseLine(Line *line, int sideNum, struct mobj_s *thing);
+
 int XL_ShootLine(Line *line, int sideNum, struct mobj_s *thing);
+
 int XL_HitLine(Line *line, int sideNum, struct mobj_s *thing);
 
 int XG_RandomInt(int min, int max);
 
 #ifdef __cplusplus
 void SV_WriteXGLine(Line *li, MapStateWriter *msw);
+
 void SV_ReadXGLine(Line *li, MapStateReader *msr);
 
 } // extern "C"