From 6e4122e551eeb41d3e950b363dd837d5586fe560 Mon Sep 17 00:00:00 2001 From: Mattes D Date: Fri, 31 Jul 2015 16:49:10 +0200 Subject: Unified the doxy-comment format. --- src/UI/SlotArea.h | 46 +++++++++++++++++++++----------------------- src/UI/Window.h | 54 +++++++++++++++++++++++++--------------------------- src/UI/WindowOwner.h | 20 ++++++------------- 3 files changed, 54 insertions(+), 66 deletions(-) (limited to 'src/UI') diff --git a/src/UI/SlotArea.h b/src/UI/SlotArea.h index cd340408a..b150c47a1 100644 --- a/src/UI/SlotArea.h +++ b/src/UI/SlotArea.h @@ -35,19 +35,19 @@ public: int GetNumSlots(void) const { return m_NumSlots; } - /// Called to retrieve an item in the specified slot for the specified player. Must return a valid cItem. + /** Called to retrieve an item in the specified slot for the specified player. Must return a valid cItem. */ virtual const cItem * GetSlot(int a_SlotNum, cPlayer & a_Player) const = 0; - /// Called to set an item in the specified slot for the specified player + /** Called to set an item in the specified slot for the specified player */ virtual void SetSlot(int a_SlotNum, cPlayer & a_Player, const cItem & a_Item) = 0; - /// Called when a player clicks in the window. Parameters taken from the click packet. + /** Called when a player clicks in the window. Parameters taken from the click packet. */ virtual void Clicked(cPlayer & a_Player, int a_SlotNum, eClickAction a_ClickAction, const cItem & a_ClickedItem); - /// Called from Clicked when the action is a shiftclick (left or right) + /** Called from Clicked when the action is a shiftclick (left or right) */ virtual void ShiftClicked(cPlayer & a_Player, int a_SlotNum, const cItem & a_ClickedItem); - /// Called from Clicked when the action is a caDblClick + /** Called from Clicked when the action is a caDblClick */ virtual void DblClicked(cPlayer & a_Player, int a_SlotNum); /** Called from Clicked when the action is a middleclick */ @@ -59,24 +59,23 @@ public: /** Called from Clicked when the action is a number click. */ virtual void NumberClicked(cPlayer & a_Player, int a_SlotNum, eClickAction a_ClickAction); - /// Called when a new player opens the same parent window. The window already tracks the player. CS-locked. + /** Called when a new player opens the same parent window. The window already tracks the player. CS-locked. */ virtual void OnPlayerAdded(cPlayer & a_Player); - /// Called when one of the players closes the parent window. The window already doesn't track the player. CS-locked. + /** Called when one of the players closes the parent window. The window already doesn't track the player. CS-locked. */ virtual void OnPlayerRemoved(cPlayer & a_Player); /** Called to store as much of a_ItemStack in the area as possible. a_ItemStack is modified to reflect the change. The default implementation searches each slot for available space and distributes the stack there. if a_ShouldApply is true, the changes are written into the slots; if a_ShouldApply is false, only a_ItemStack is modified to reflect the number of fits (for fit-testing purposes) - If a_KeepEmptySlots is true, empty slots will be skipped and won't be filled - */ + If a_KeepEmptySlots is true, empty slots will be skipped and won't be filled */ virtual void DistributeStack(cItem & a_ItemStack, cPlayer & a_Player, bool a_ShouldApply, bool a_KeepEmptySlots, bool a_BackFill); - /// Called on DblClicking to collect all stackable items into hand. - /// The items are accumulated in a_Dragging and removed from the slots immediately. - /// If a_CollectFullStacks is false, slots with full stacks are skipped while collecting. - /// Returns true if full stack has been collected in a_Dragging, false if there's space remaining to fill. + /** Called on DblClicking to collect all stackable items into hand. + The items are accumulated in a_Dragging and removed from the slots immediately. + If a_CollectFullStacks is false, slots with full stacks are skipped while collecting. + Returns true if full stack has been collected in a_Dragging, false if there's space remaining to fill. */ virtual bool CollectItemsToHand(cItem & a_Dragging, cPlayer & a_Player, bool a_CollectFullStacks); protected: @@ -88,7 +87,7 @@ protected: -/// Handles any part of the inventory, using parameters in constructor to distinguish between the parts +/** Handles any part of the inventory, using parameters in constructor to distinguish between the parts */ class cSlotAreaInventoryBase : public cSlotArea { @@ -111,7 +110,7 @@ protected: -/// Handles the main inventory of each player, excluding the armor and hotbar +/** Handles the main inventory of each player, excluding the armor and hotbar */ class cSlotAreaInventory : public cSlotAreaInventoryBase { @@ -128,7 +127,7 @@ public: -/// Handles the hotbar of each player +/** Handles the hotbar of each player */ class cSlotAreaHotBar : public cSlotAreaInventoryBase { @@ -145,7 +144,7 @@ public: -/// Handles the armor area of the player's inventory +/** Handles the armor area of the player's inventory */ class cSlotAreaArmor : public cSlotAreaInventoryBase { @@ -168,7 +167,7 @@ public: -/// Handles any slot area that is representing a cItemGrid; same items for all the players +/** Handles any slot area that is representing a cItemGrid; same items for all the players */ class cSlotAreaItemGrid : public cSlotArea, public cItemGrid::cListener @@ -196,8 +195,7 @@ protected: /** A cSlotArea with items layout that is private to each player and is temporary, such as a crafting grid or an enchantment table. -This common ancestor stores the items in a per-player map. It also implements tossing items from the map. -*/ +This common ancestor stores the items in a per-player map. It also implements tossing items from the map. */ class cSlotAreaTemporary : public cSlotArea { @@ -212,7 +210,7 @@ public: virtual void OnPlayerAdded (cPlayer & a_Player) override; virtual void OnPlayerRemoved(cPlayer & a_Player) override; - /// Tosses the player's items in slots [a_Begin, a_End) (ie. incl. a_Begin, but excl. a_End) + /** Tosses the player's items in slots [a_Begin, a_End) (ie. incl. a_Begin, but excl. a_End) */ void TossItems(cPlayer & a_Player, int a_Begin, int a_End); protected: @@ -220,7 +218,7 @@ protected: cItemMap m_Items; - /// Returns the pointer to the slot array for the player specified. + /** Returns the pointer to the slot array for the player specified. */ cItem * GetPlayerSlots(cPlayer & a_Player); } ; @@ -234,7 +232,7 @@ class cSlotAreaCrafting : typedef cSlotAreaTemporary super; public: - /// a_GridSize is allowed to be only 2 or 3 + /** a_GridSize is allowed to be only 2 or 3 */ cSlotAreaCrafting(int a_GridSize, cWindow & a_ParentWindow); // cSlotAreaTemporary overrides: @@ -450,7 +448,7 @@ protected: // cItemGrid::cListener overrides: virtual void OnSlotChanged(cItemGrid * a_ItemGrid, int a_SlotNum) override; - /// Called after an item has been smelted to handle statistics etc. + /** Called after an item has been smelted to handle statistics etc. */ void HandleSmeltItem(const cItem & a_Result, cPlayer & a_Player); } ; diff --git a/src/UI/Window.h b/src/UI/Window.h index 156028465..cb8f40767 100644 --- a/src/UI/Window.h +++ b/src/UI/Window.h @@ -81,35 +81,35 @@ public: cWindowOwner * GetOwner(void) { return m_Owner; } void SetOwner( cWindowOwner * a_Owner) { m_Owner = a_Owner; } - /// Returns the total number of slots + /** Returns the total number of slots */ int GetNumSlots(void) const; - /// Returns the number of slots, excluding the player's inventory (used for network protocols) + /** Returns the number of slots, excluding the player's inventory (used for network protocols) */ int GetNumNonInventorySlots(void) const { return GetNumSlots() - c_NumInventorySlots; } // tolua_begin - /// Returns the item at the specified slot for the specified player. Returns nullptr if invalid SlotNum requested + /** Returns the item at the specified slot for the specified player. Returns nullptr if invalid SlotNum requested */ const cItem * GetSlot(cPlayer & a_Player, int a_SlotNum) const; - /// Sets the item to the specified slot for the specified player + /** Sets the item to the specified slot for the specified player */ void SetSlot(cPlayer & a_Player, int a_SlotNum, const cItem & a_Item); - /// Returns true if the specified slot is in the Player Main Inventory slotarea + /** Returns true if the specified slot is in the Player Main Inventory slotarea */ bool IsSlotInPlayerMainInventory(int a_SlotNum) const; - /// Returns true if the specified slot is in the Player Hotbar slotarea + /** Returns true if the specified slot is in the Player Hotbar slotarea */ bool IsSlotInPlayerHotbar(int a_SlotNum) const; - /// Returns true if the specified slot is in the Player Main Inventory or Hotbar slotareas. Note that returns false for Armor. + /** Returns true if the specified slot is in the Player Main Inventory or Hotbar slotareas. Note that returns false for Armor. */ bool IsSlotInPlayerInventory(int a_SlotNum) const; // tolua_end - /// Fills a_Slots with the slots read from m_SlotAreas[], for the specified player + /** Fills a_Slots with the slots read from m_SlotAreas[], for the specified player */ void GetSlots(cPlayer & a_Player, cItems & a_Slots) const; - /// Handles a click event from a player + /** Handles a click event from a player */ void Clicked( cPlayer & a_Player, int a_WindowID, short a_SlotNum, eClickAction a_ClickAction, @@ -118,16 +118,16 @@ public: virtual void OpenedByPlayer(cPlayer & a_Player); - /// Called when a player closes this window; notifies all slot areas. Returns true if close accepted + /** Called when a player closes this window; notifies all slot areas. Returns true if close accepted */ virtual bool ClosedByPlayer(cPlayer & a_Player, bool a_CanRefuse); - /// Sends the specified slot's contents to all clients of this window; the slot is specified as local in an area + /** Sends the specified slot's contents to all clients of this window; the slot is specified as local in an area */ void BroadcastSlot(cSlotArea * a_Area, int a_LocalSlotNum); - /// Sends the contents of the whole window to the specified client + /** Sends the contents of the whole window to the specified client */ void SendWholeWindow(cClientHandle & a_Client); - /// Sends the contents of the whole window to all clients of this window. + /** Sends the contents of the whole window to all clients of this window. */ void BroadcastWholeWindow(void); // tolua_begin @@ -135,20 +135,20 @@ public: const AString & GetWindowTitle() const { return m_WindowTitle; } void SetWindowTitle(const AString & a_WindowTitle) { m_WindowTitle = a_WindowTitle; } - /// Sends the UpdateWindowProperty (0x69) packet to all clients of the window + /** Sends the UpdateWindowProperty (0x69) packet to all clients of the window */ virtual void SetProperty(short a_Property, short a_Value); - /// Sends the UpdateWindowPropert(0x69) packet to the specified player + /** Sends the UpdateWindowPropert(0x69) packet to the specified player */ virtual void SetProperty(short a_Property, short a_Value, cPlayer & a_Player); // tolua_end void OwnerDestroyed(void); - /// Calls the callback safely for each player that has this window open; returns true if all players have been enumerated + /** Calls the callback safely for each player that has this window open; returns true if all players have been enumerated */ bool ForEachPlayer(cItemCallback & a_Callback); - /// Calls the callback safely for each client that has this window open; returns true if all clients have been enumerated + /** Calls the callback safely for each client that has this window open; returns true if all clients have been enumerated */ bool ForEachClient(cItemCallback & a_Callback); /** Called on shift-clicking to distribute the stack into other areas; Modifies a_ItemStack as it is distributed! @@ -168,7 +168,7 @@ public: Returns true if full stack has been collected, false if there's space remaining to fill. */ bool CollectItemsToHand(cItem & a_Dragging, cSlotArea & a_Area, cPlayer & a_Player, bool a_CollectFullStacks); - /// Used by cSlotAreas to send individual slots to clients, a_RelativeSlotNum is the slot number relative to a_SlotArea + /** Used by cSlotAreas to send individual slots to clients, a_RelativeSlotNum is the slot number relative to a_SlotArea */ void SendSlot(cPlayer & a_Player, cSlotArea * a_SlotArea, int a_RelativeSlotNum); protected: @@ -187,35 +187,33 @@ protected: static Byte m_WindowIDCounter; - /// Sets the internal flag as "destroyed"; notifies the owner that the window is destroying + /** Sets the internal flag as "destroyed"; notifies the owner that the window is destroying */ virtual void Destroy(void); /** Returns the correct slot area for the specified window-global SlotNum Also returns the area-local SlotNum corresponding to the GlobalSlotNum - If the global SlotNum is out of range, returns nullptr - */ + If the global SlotNum is out of range, returns nullptr */ cSlotArea * GetSlotArea(int a_GlobalSlotNum, int & a_LocalSlotNum); /** Returns the correct slot area for the specified window-global SlotNum Also returns the area-local SlotNum corresponding to the GlobalSlotNum If the global SlotNum is out of range, returns nullptr. - Const version. - */ + Const version. */ const cSlotArea * GetSlotArea(int a_GlobalSlotNum, int & a_LocalSlotNum) const; - /// Prepares the internal structures for inventory painting from the specified player + /** Prepares the internal structures for inventory painting from the specified player */ void OnPaintBegin(cPlayer & a_Player); - /// Adds the slot to the internal structures for inventory painting by the specified player + /** Adds the slot to the internal structures for inventory painting by the specified player */ void OnPaintProgress(cPlayer & a_Player, int a_SlotNum); - /// Processes the entire action stored in the internal structures for inventory painting; distributes as many items as possible + /** Processes the entire action stored in the internal structures for inventory painting; distributes as many items as possible */ void OnLeftPaintEnd(cPlayer & a_Player); - /// Processes the entire action stored in the internal structures for inventory painting; distributes one item into each slot + /** Processes the entire action stored in the internal structures for inventory painting; distributes one item into each slot */ void OnRightPaintEnd(cPlayer & a_Player); - /// Distributes a_NumToEachSlot items into the slots specified in a_SlotNums; returns the total number of items distributed + /** Distributes a_NumToEachSlot items into the slots specified in a_SlotNums; returns the total number of items distributed */ int DistributeItemToSlots(cPlayer & a_Player, const cItem & a_Item, int a_NumToEachSlot, const cSlotNums & a_SlotNums); } ; // tolua_export diff --git a/src/UI/WindowOwner.h b/src/UI/WindowOwner.h index 4dc3cf080..72a5348c4 100644 --- a/src/UI/WindowOwner.h +++ b/src/UI/WindowOwner.h @@ -4,20 +4,16 @@ #include "../Entities/Entity.h" #include "Window.h" -/* -Being a descendant of cWindowOwner means that the class can own one window. That window can be +/* Being a descendant of cWindowOwner means that the class can own one window. That window can be queried, opened by other players, closed by players and finally destroyed. Also, a cWindowOwner can be queried for the block coords where the window is displayed. That will be used -for entities / players in motion to close their windows when they get too far away from the window "source". -*/ +for entities / players in motion to close their windows when they get too far away from the window "source". */ -/** -Base class for the window owning -*/ +/** Base class for the window owning */ class cWindowOwner { public: @@ -46,7 +42,7 @@ public: return m_Window; } - /// Returns the block position at which the element owning the window is + /** Returns the block position at which the element owning the window is */ virtual Vector3i GetBlockPos(void) = 0; private: @@ -57,9 +53,7 @@ private: -/** -Window owner that is associated with a block entity (chest, furnace, ...) -*/ +/** Window owner that is associated with a block entity (chest, furnace, ...) */ class cBlockEntityWindowOwner : public cWindowOwner { @@ -82,9 +76,7 @@ private: -/** -Window owner that is associated with an entity (chest minecart) -*/ +/** Window owner that is associated with an entity (chest minecart etc.) */ class cEntityWindowOwner : public cWindowOwner { -- cgit v1.2.3