From: Martin Read <martin@blackswordsonics.com>
Date: Wed, 26 Feb 2014 03:41:58 +0000 (+0000)
Subject: Doxygenation and staticization
X-Git-Url: http://git.blackswordsonics.com/?a=commitdiff_plain;h=f59514ed8074f42e4ef196015a8c6336ea568024;p=victrix-abyssi

Doxygenation and staticization

* display-nc.cc: Made a bunch of things static that didn't need to be extern, and gave everything at least a doxygen 'brief' description.
---

diff --git a/display-nc.cc b/display-nc.cc
index ffd1b1e..f81e68e 100644
--- a/display-nc.cc
+++ b/display-nc.cc
@@ -43,36 +43,77 @@
 //#define DEBUG_TO_STDERR
 #define DISP_NC_RADIUS (10)
 #define DISP_NC_SIDE (DISP_NC_RADIUS * 2 + 1)
-void set_inventory_message(char const *s, bool allow_nil);
-void reset_inventory_message(void);
-void hide_inv(void);
-void show_inv(void);
-void update_inv(enum poclass_num filter);
-int inv_select(enum poclass_num filter, char const *action, int accept_blank);
+
+/* Prototypes for static funcs */
+static cchar_t const *object_char(int object_id);
+static cchar_t const *monster_char(int monster_id);
+static cchar_t const *terrain_char(Terrain terrain_type);
+static void draw_status_line(void);
+static void draw_world(void);
+static void draw_main_menu(void);
+static void run_main_menu(void);
+
+static void set_inventory_message(char const *s, bool allow_nil);
+static void reset_inventory_message(void);
+static void hide_inv(void);
+static void show_inv(void);
+static void update_inv(enum poclass_num filter);
+static int inv_select(enum poclass_num filter, char const *action, int accept_blank);
 static void farlook(void);
-WINDOW *status_window;
-WINDOW *world_window;
-WINDOW *message_window;
-WINDOW *inventory_window;
-WINDOW *fullscreen_window; /* discrete from stdscr because *twitch* */
-PANEL *status_panel;
-PANEL *world_panel;
-PANEL *message_panel;
-PANEL *inventory_panel;
-PANEL *fullscreen_panel;
-bool force_ascii;
 
+/*! \brief For showing the player's status summary */
+static WINDOW *status_window;
+
+/*! \brief For showing the area around the player. */
+static WINDOW *world_window;
+
+/*! \brief For showing recent messages. */
+static WINDOW *message_window;
+
+/*! \brief For showing the player's inventory without smashing the messages */
+static WINDOW *inventory_window;
+
+/*! \brief 24x80 window for title screen etc. */
+static WINDOW *fullscreen_window;
+
+/*! \brief PANEL for the status window */
+static PANEL *status_panel;
+
+/*! \brief PANEL for the world window */
+static PANEL *world_panel;
+
+/*! \brief PANEL for the message window */
+static PANEL *message_panel;
+
+/*! \brief PANEL for the inventory window */
+static PANEL *inventory_panel;
+
+/*! \brief PANEL for the title screen etc. */
+static PANEL *fullscreen_panel;
+
+/*! \brief Should we coerce the tiles to ASCII? */
+static bool force_ascii;
+
+/*! \brief Flag indicating the player's status has changed */
 bool status_updated;
+
+/*! \brief Flag indicating the map has changed redrawn */
 bool map_updated;
+
+/*! \brief Flag indicating that the terrain should be drawn in preference to objects/monsters */
 bool show_terrain;
+
+/*! \brief Flag indicating a more comprehensive redraw of the map */
 bool hard_redraw;
 
+/*! \brief ncursesw attribute and colorpair for a game colour */
 struct Attr_wrapper 
 {
     attr_t attr;
     short cpair;
 };
 
+/*! \brief The list of attributes/colorpairs for the game's colours */
 Attr_wrapper colour_data[1 + LAST_COLOUR] =
 {
     { 0, Gcol_l_grey },
@@ -102,22 +143,31 @@ Attr_wrapper colour_data[1 + LAST_COLOUR] =
     { A_BOLD, Gcol_blue }
 };
 
+/*! \brief ncursesw objects for drawing terrain */
 cchar_t terrain_tiles[NUM_TERRAINS];
 
+/*! \brief ncursesw objects for drawing items */
 cchar_t permobj_tiles[NUM_OF_PERMOBJS];
 
 #define DISP_HEIGHT (DISP_NC_SIDE)
 #define DISP_WIDTH (DISP_NC_SIDE)
 
+/*! \brief ncursesw objects for drawing monsters */
 cchar_t permon_tiles[NUM_OF_PERMONS];
 
+/*! \brief ncursesw object for drawing unexplored space */
 cchar_t blank_tile;
+
+/*! \brief ncursesw object for drawing player */
 cchar_t player_tile;
+
+/*! \brief Cached tile pointer for what we should draw next time we refresh the map */
 cchar_t const *back_buffer[DISP_HEIGHT][DISP_WIDTH];
-Attr_wrapper attr_override[DISP_HEIGHT][DISP_WIDTH];
+
+/*! \brief Cached tile pointer for what's currently on screen */
 cchar_t const *front_buffer[DISP_HEIGHT][DISP_WIDTH];
 
-/* These were in misc.cc, but nothing else was. Ergo, delete misc.cc */
+/*! \brief Printable English-language names for damage types */
 char const *damtype_names[DT_COUNT] = {
     "physical damage",
     "cold",
@@ -130,16 +180,7 @@ char const *damtype_names[DT_COUNT] = {
     "drowning",
 };
 
-/* Prototypes for static funcs */
-static cchar_t const *object_char(int object_id);
-static cchar_t const *monster_char(int monster_id);
-static cchar_t const *terrain_char(Terrain terrain_type);
-static void draw_status_line(void);
-static void draw_world(void);
-static void draw_main_menu(void);
-static void run_main_menu(void);
-
-/* Static funcs */
+/*! \brief Draw the main menu. */
 static void draw_main_menu(void)
 {
     wclear(fullscreen_window);
@@ -154,6 +195,7 @@ static void draw_main_menu(void)
     doupdate();
 }
 
+/*! \brief Redraw the status line. */
 static void draw_status_line(void)
 {
     mvwprintw(status_window, 0, 0, "%-16.16s", u.name);
@@ -167,28 +209,36 @@ static void draw_status_line(void)
 }
 
 /*! \brief Get pointer to cchar_t object for specified terrain
+ *
+ * \param terrain_type Specified terrain type
+ * \return pointer to the specified terrain type's tile
  */
 static cchar_t const *terrain_char(Terrain terrain_type)
 {
     return terrain_tiles + terrain_type;
 }
 
-/*! \brief Get pointer to cchar_t object for specified monster
+/*! \brief Get pointer to cchar_t object for specified permon
+ *
+ * \param monster_id Specified permon
+ * \return pointer to the specified permon's tile
  */
 static cchar_t const *monster_char(int monster_id)
 {
     return permon_tiles + monster_id;
 }
 
-/*! \brief Get pointer to cchar_t object for specified object
+/*! \brief Get pointer to cchar_t object for specified permobj
+ *
+ * \param object_id Specified permobj
+ * \return pointer to the specified permobj's tile
  */
 static cchar_t const *object_char(int object_id)
 {
     return permobj_tiles + object_id;
 }
 
-/*! \brief Repopulate the back buffer and set the hard redraw flag
- */
+/*! \brief Repopulate the back buffer and set the hard redraw flag */
 void touch_back_buffer(void)
 {
     Coord c;
@@ -208,6 +258,8 @@ void touch_back_buffer(void)
  * newsym() notifies the display layer that the state of position 'c' has
  * changed in a way that should change its graphical representation (e.g.
  * there was a monster there and now there isn't).
+ *
+ * \param c Location to update appearance of
  */
 void newsym(Coord c)
 {
@@ -260,8 +312,7 @@ void newsym(Coord c)
     }
 }
 
-/*! \brief Update the map window
- */
+/*! \brief Update the map window */
 static void draw_world(void)
 {
     int i;
@@ -288,7 +339,8 @@ static void draw_world(void)
     }
 }
 
-static void load_unicode_tiles()
+/*! \brief Set up the tiles in unicode mode */
+static void load_unicode_tiles(void)
 {
     int i;
     int j;
@@ -339,7 +391,8 @@ static void load_unicode_tiles()
     }
 }
 
-static void load_ascii_tiles()
+/*! \brief Set up the tiles in ASCII mode */
+static void load_ascii_tiles(void)
 {
     int i;
     {
@@ -381,8 +434,7 @@ static void load_ascii_tiles()
 
 /* extern funcs */
 
-/*! \brief Wait for the user to press RETURN
- */
+/*! \brief Wait for the user to press RETURN */
 void press_enter(void)
 {
     int ch;
@@ -397,8 +449,7 @@ void press_enter(void)
     }
 }
 
-/*! \brief Update any parts of the display that need it
- */
+/*! \brief Update any parts of the display that need it */
 void display_update(void)
 {
     if (status_updated)
@@ -553,6 +604,9 @@ int launch_user_interface(void)
 }
 
 /*! \brief Get string input from the player
+ *
+ * \param buffer destination for player input
+ * \param length maximum length of buffer
  */
 int read_input(char *buffer, int length)
 {
@@ -573,7 +627,6 @@ int read_input(char *buffer, int length)
  *  the player should be flagged *before* print_msg() is called with the
  *  message announcing the change.
  *
- *  \param prio Message priority
  *  \param fmt printf-style format string
  *  \todo Handle the message window getting resized.
  *  \todo Implement message scrollback.
@@ -649,7 +702,7 @@ void print_msg(Msg_prio prio, char const *fmt, ...)
  *  \param s Message to set.
  *  \param allow_nil Whether the 'nothing' option should be listed.
  */
-void set_inventory_message(char const *s, bool allow_nil)
+static void set_inventory_message(char const *s, bool allow_nil)
 {
     mvwprintw(inventory_window, 0, 0, "%-57s\n", s);
     if (!allow_nil)
@@ -662,27 +715,24 @@ void set_inventory_message(char const *s, bool allow_nil)
     }
 }
 
-/*! \brief Clear any inventory message
- */
-void reset_inventory_message(void)
+/*! \brief Clear any inventory message */
+static void reset_inventory_message(void)
 {
     wattr_set(inventory_window, colour_data[Gcol_l_grey].attr, colour_data[Gcol_l_grey].cpair, nullptr);
     mvwprintw(inventory_window, 0, 0, "                     === INVENTORY ===");
     mvwprintw(inventory_window, 20, 0, "                 ");
 }
 
-/*! \brief Make the inventory visible
- */
-void show_inv(void)
+/*! \brief Make the inventory visible */
+static void show_inv(void)
 {
     show_panel(inventory_panel);
     update_panels();
     doupdate();
 }
 
-/*! \brief Hide the inventory if necessary on this display type
- */
-void hide_inv(void)
+/*! \brief Hide the inventory if necessary on this display type */
+static void hide_inv(void)
 {
     show_panel(message_panel);
     hide_panel(inventory_panel);
@@ -692,9 +742,10 @@ void hide_inv(void)
 
 /*! \brief Update the inventory window to reflect the filter in force
  *
+ * \param filter Class of objects to highlight; (POCLASS_NONE to highlight all)
  *  \todo Switch to using a function pointer + private argument for filtering
  */
-void update_inv(enum poclass_num filter)
+static void update_inv(enum poclass_num filter)
 {
     int i;
     char inv_line[60];
@@ -734,9 +785,12 @@ void update_inv(enum poclass_num filter)
 
 /*! \brief Select an inventory item
  *
+ * \param filter Type of item to accept
+ * \param action Verb to use in prompt
+ * \param accept_blank If true, the pseudo-item "nothing" can be selected
  * \todo Take function pointer and private arg for smarter filtering
  */
-int inv_select(enum poclass_num filter, char const *action, int accept_blank)
+static int inv_select(enum poclass_num filter, char const *action, int accept_blank)
 {
     int selection;
     int ch;
@@ -818,6 +872,7 @@ tryagain:
 
 /*! \brief Ask the player to choose a direction
  *
+ * \param pstep Location to store direction's Offset value in
  * \todo Consider making this accommodate up/down/self as well as compass directions
  */
 Pass_fail select_dir(Offset *pstep)
@@ -884,6 +939,7 @@ Pass_fail select_dir(Offset *pstep)
 
 /*! \brief Read the player's next command
  *
+ * \param act Location to store new command in
  * \todo Consider redesigning in a way friendlier to non-terminal platforms
  */
 void get_player_action(Action *act)
@@ -1279,6 +1335,8 @@ void get_player_action(Action *act)
 }
 
 /*! \brief Shut down the display subsystem
+ *
+ * \return 0 normally, -1 if error.
  */
 int display_shutdown(void)
 {
@@ -1288,8 +1346,7 @@ int display_shutdown(void)
     return 0;
 }
 
-/*! \brief Prompt the player to press any key 
- */
+/*! \brief Prompt the player to press any key */
 void pressanykey(void)
 {
     print_msg("Press any key to continue.\n");
@@ -1297,6 +1354,8 @@ void pressanykey(void)
 }
 
 /*! \brief Prompt the player for a relatively paranoid 'Y'
+ *
+ * \param msg Question to ask the player
  */
 int getYN(char const *msg)
 {
@@ -1312,6 +1371,8 @@ int getYN(char const *msg)
 }
 
 /*! \brief Get a yes/no response from the player
+ *
+ * \param msg Question to ask the player
  */
 int getyn(char const *msg)
 {
@@ -1409,6 +1470,8 @@ void print_help(void)
 }
 
 /*! \brief Call newsym() for all locations in camera range of a position
+ *
+ * \param c Position to update around
  */
 void touch_one_screen(Coord c)
 {