[Freeciv-Dev] Re: (PR#12643) Unify comments for gui specific client functions

["Raimar Falke" <i-freeciv-lists@xxxxxxxxxxxxx>]

<URL: http://bugs.freeciv.org/Ticket/Display.html?id=12643 >

On Fri, Mar 25, 2005 at 09:52:12AM -0800, Raimar Falke wrote:
> I'm not sure how to procede from here. There are 70 functions with a
> conflict and 6 without a comment. When we resolved these conflicts I
> can write a script to update all other function comments based on the
> one from gui-stub.

Here is a patch which updates the docu in gui-stub. Jason can you
please check and apply the patch?

        Raimar

-- 
 email: i-freeciv-lists@xxxxxxxxxxxxx
 "A common mistake that people make, when trying to design 
  something completely foolproof is to underestimate the 
  ingenuity of complete fools."
    -- Douglas Adams in Mostly Harmless

Index: client/gui-mui/graphics.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-mui/graphics.c,v
retrieving revision 1.37
diff -u -u -r1.37 graphics.c
--- client/gui-mui/graphics.c   11 Mar 2005 17:11:26 -0000      1.37
+++ client/gui-mui/graphics.c   26 Mar 2005 15:25:41 -0000
@@ -84,12 +84,15 @@
 /****************************************************************
  Crop a sprite from a bigger sprite (called from the gui
  independend part)
- Note that the ImageData is not copied but only referenced,
- this saves memory (because Data of BitMaps are aligned) and
- loading time
 *****************************************************************/
 struct Sprite *crop_sprite(struct Sprite *source, int x, int y, int width, int 
height)
 {
+  /* 
+   * Note that the ImageData is not copied but only referenced, this
+   * saves memory (because Data of BitMaps are aligned) and loading
+   * time.
+   */
+
   struct Sprite *sprite = (struct Sprite *) malloc(sizeof(struct Sprite));
 
   if (sprite)
Index: client/gui-stub/canvas.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/canvas.c,v
retrieving revision 1.1
diff -u -u -r1.1 canvas.c
--- client/gui-stub/canvas.c    23 Mar 2005 17:56:54 -0000      1.1
+++ client/gui-stub/canvas.c    26 Mar 2005 15:25:41 -0000
@@ -46,7 +46,7 @@
 }
 
 /****************************************************************************
-  Draw some or all of a sprite onto the mapview or citydialog canvas.
+  Draw some or all of a sprite onto the canvas.
 ****************************************************************************/
 void canvas_put_sprite(struct canvas *pcanvas,
                    int canvas_x, int canvas_y,
@@ -57,7 +57,7 @@
 }
 
 /****************************************************************************
-  Draw a full sprite onto the mapview or citydialog canvas.
+  Draw a full sprite onto the canvas.
 ****************************************************************************/
 void canvas_put_sprite_full(struct canvas *pcanvas,
                         int canvas_x, int canvas_y,
@@ -79,7 +79,7 @@
 }
 
 /****************************************************************************
-  Draw a filled-in colored rectangle onto the mapview or citydialog canvas.
+  Draw a filled-in colored rectangle onto canvas.
 ****************************************************************************/
 void canvas_put_rectangle(struct canvas *pcanvas,
                       enum color_std color,
@@ -108,7 +108,7 @@
 }
 
 /****************************************************************************
-  Draw a 1-pixel-width colored line onto the mapview or citydialog canvas.
+  Draw a 1-pixel-width colored line onto the canvas.
 ****************************************************************************/
 void canvas_put_line(struct canvas *pcanvas, enum color_std color,
                  enum line_type ltype, int start_x, int start_y,
Index: client/gui-stub/cityrep.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/cityrep.c,v
retrieving revision 1.6
diff -u -u -r1.6 cityrep.c
--- client/gui-stub/cityrep.c   25 Nov 2004 06:57:17 -0000      1.6
+++ client/gui-stub/cityrep.c   26 Mar 2005 15:25:41 -0000
@@ -36,7 +36,7 @@
 }
 
 /**************************************************************************
-  Update the city report dialog for a single city.
+  Update the information for a single city in the city report.
 **************************************************************************/
 void city_report_dialog_update_city(struct city *pcity)
 {
Index: client/gui-stub/connectdlg.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/connectdlg.c,v
retrieving revision 1.12
diff -u -u -r1.12 connectdlg.c
--- client/gui-stub/connectdlg.c        9 Sep 2004 21:22:34 -0000       1.12
+++ client/gui-stub/connectdlg.c        26 Mar 2005 15:25:41 -0000
@@ -33,7 +33,7 @@
 
 
 /**************************************************************************
- really close and destroy the dialog.
+ Really close and destroy the dialog.
 **************************************************************************/
 void really_close_connection_dialog(void)
 {
@@ -41,7 +41,8 @@
 }
 
 /**************************************************************************
- close and destroy the dialog.
+ Close and destroy the dialog. But only if we don't have a local
+ server running (that we started).
 **************************************************************************/
 void close_connection_dialog()
 {
@@ -49,7 +50,7 @@
 }
 
 /**************************************************************************
- configure the dialog depending on what type of authentication request the
+ Configure the dialog depending on what type of authentication request the
  server is making.
 **************************************************************************/
 void handle_authentication_req(enum authentication_type type, char *message)
@@ -85,7 +86,10 @@
 }
 
 /**************************************************************************
- provide a packet handler for packet_game_load
+ Provide a packet handler for packet_game_load.
+
+ This regenerates the player information from a loaded game on the
+ server.
 **************************************************************************/
 void handle_game_load(struct packet_game_load *packet)
 { 
Index: client/gui-stub/diplodlg.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/diplodlg.c,v
retrieving revision 1.5
diff -u -u -r1.5 diplodlg.c
--- client/gui-stub/diplodlg.c  23 Feb 2004 20:03:56 -0000      1.5
+++ client/gui-stub/diplodlg.c  26 Mar 2005 15:25:41 -0000
@@ -65,6 +65,8 @@
 
 /**************************************************************************
   Close all open diplomacy dialogs.
+
+  Called when the client disconnects from game.
 **************************************************************************/
 void close_all_diplomacy_dialogs(void)
 {
Index: client/gui-stub/gui_main.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/gui_main.c,v
retrieving revision 1.17
diff -u -u -r1.17 gui_main.c
--- client/gui-stub/gui_main.c  21 Mar 2005 23:14:08 -0000      1.17
+++ client/gui-stub/gui_main.c  26 Mar 2005 15:25:41 -0000
@@ -85,6 +85,9 @@
 /**************************************************************************
   Wait for data on the given socket.  Call input_from_server() when data
   is ready to be read.
+
+  This function is called after the client succesfully has connected
+  to the server.
 **************************************************************************/
 void add_net_input(int sock)
 {
@@ -93,6 +96,8 @@
 
 /**************************************************************************
   Stop waiting for any server network data.  See add_net_input().
+
+  This function is called if the client disconnects from the server.
 **************************************************************************/
 void remove_net_input(void)
 {
@@ -100,9 +105,14 @@
 }
 
 /**************************************************************************
-  Set one of the unit icons in the information area based on punit.
-  NULL will be pased to clear the icon. idx==-1 will be passed to
-  indicate this is the active unit, or idx in [0..num_units_below-1] for
+  Set one of the unit icons (specified by idx) in the information area
+  based on punit.
+
+  punit is the unit the information should be taken from. Use NULL to
+  clear the icon.
+
+  idx specified which icon should be modified. Use idx==-1 to indicate
+  the icon for the active unit. Or idx in [0..num_units_below-1] for
   secondary (inactive) units on the same tile.
 **************************************************************************/
 void set_unit_icon(int idx, struct unit *punit)
@@ -112,8 +122,10 @@
 
 /**************************************************************************
   Most clients use an arrow (e.g., sprites.right_arrow) to indicate when
-  the units_below will not fit. This function is called to activate and
+  the units_below will not fit. This function is called to activate or
   deactivate the arrow.
+
+  Is disabled by default.
 **************************************************************************/
 void set_unit_icons_more_arrow(bool onoff)
 {
Index: client/gui-stub/helpdlg.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/helpdlg.c,v
retrieving revision 1.4
diff -u -u -r1.4 helpdlg.c
--- client/gui-stub/helpdlg.c   30 Nov 2002 19:27:37 -0000      1.4
+++ client/gui-stub/helpdlg.c   26 Mar 2005 15:25:41 -0000
@@ -20,11 +20,11 @@
 #include "helpdlg.h"
 
 /**************************************************************************
-  Popup the help dialog to get help on the given string topic.  Note that
-  the toppic may appear in multiple sections of the help (it may be both
-  an improvement and a unit, for example).
+  Popup the help dialog to get help on the given string topic.  Note
+  that the topic may appear in multiple sections of the help (it may
+  be both an improvement and a unit, for example).
 
-  The string will be untranslated.
+  The given string should be untranslated.
 **************************************************************************/
 void popup_help_dialog_string(const char *item)
 {
Index: client/gui-stub/mapview.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/mapview.c,v
retrieving revision 1.52
diff -u -u -r1.52 mapview.c
--- client/gui-stub/mapview.c   23 Mar 2005 17:56:54 -0000      1.52
+++ client/gui-stub/mapview.c   26 Mar 2005 15:25:41 -0000
@@ -51,16 +51,16 @@
 }
 
 /****************************************************************************
-  Update the information label which gives info on the current unit and
-  the square under the current unit, for specified unit.  Note that in
-  practice punit is always the focus unit.
+  Update the information label which gives info on the current unit
+  and the tile under the current unit, for specified unit.  Note that
+  in practice punit is always the focus unit.
 
   Clears label if punit is NULL.
 
-  Typically also updates the cursor for the map_canvas (this is related
-  because the info label may includes  "select destination" prompt etc).
-  And it may call update_unit_pix_label() to update the icons for units
-  on this square.
+  Typically also updates the cursor for the map_canvas (this is
+  related because the info label may includes "select destination"
+  prompt etc).  And it may call update_unit_pix_label() to update the
+  icons for units on this tile.
 ****************************************************************************/
 void update_unit_info_label(struct unit *punit)
 {
@@ -68,8 +68,8 @@
 }
 
 /****************************************************************************
-  Update the timeout in the client window.  The timeout is the time until
-  the turn ends, in seconds.
+  Update the timeout display.  The timeout is the time until the turn
+  ends, in seconds.
 ****************************************************************************/
 void update_timeout_label(void)
 {
@@ -79,9 +79,10 @@
 }
 
 /****************************************************************************
-  If do_restore is FALSE it should change the turn button style (to draw
-  the user's attention to it).  If do_restore is TRUE this should reset
-  the turn done button to the default style.
+  If do_restore is FALSE it should change the turn button style (to
+  draw the user's attention to it).  If called regularly from a timer
+  this will give a blinking turn done button.  If do_restore is TRUE
+  this should reset the turn done button to the default style.
 ****************************************************************************/
 void update_turn_done_button(bool do_restore)
 {
@@ -141,7 +142,7 @@
 }
 
 /****************************************************************************
-  Mark the rectangular region as 'dirty' so that we know to flush it
+  Mark the rectangular region as "dirty" so that we know to flush it
   later.
 ****************************************************************************/
 void dirty_rect(int canvas_x, int canvas_y,
@@ -196,7 +197,7 @@
 }
 
 /****************************************************************************
-  Update (refresh) all of the city descriptions on the mapview.
+  Update (refresh) all city descriptions on the mapview.
 ****************************************************************************/
 void update_city_descriptions(void)
 {
Index: client/gui-stub/menu.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/menu.c,v
retrieving revision 1.3
diff -u -u -r1.3 menu.c
--- client/gui-stub/menu.c      30 Nov 2002 19:27:37 -0000      1.3
+++ client/gui-stub/menu.c      26 Mar 2005 15:25:41 -0000
@@ -18,7 +18,8 @@
 #include "menu.h"
 
 /**************************************************************************
-  Update all of the menus (sensitivity, etc.) based on the current state.
+  Update all of the menus (sensitivity, name, etc.) based on the
+  current state.
 **************************************************************************/
 void update_menus(void)
 {
Index: client/gui-stub/pages.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/pages.c,v
retrieving revision 1.4
diff -u -u -r1.4 pages.c
--- client/gui-stub/pages.c     21 Mar 2005 23:14:08 -0000      1.4
+++ client/gui-stub/pages.c     26 Mar 2005 15:25:41 -0000
@@ -20,8 +20,7 @@
 #include "pages.h"
 
 /**************************************************************************
-  Sets the "page" that the client should show.  See documentation in
-  pages_g.h.
+  Sets the "page" that the client should show.  See also pages_g.h.
 **************************************************************************/
 void set_client_page(enum client_pages page)
 {
Index: client/gui-stub/repodlgs.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/repodlgs.c,v
retrieving revision 1.11
diff -u -u -r1.11 repodlgs.c
--- client/gui-stub/repodlgs.c  25 Nov 2004 06:57:17 -0000      1.11
+++ client/gui-stub/repodlgs.c  26 Mar 2005 15:25:41 -0000
@@ -96,7 +96,7 @@
 }
 
 /*************************************************************************
-  Server options dialog
+  Show a dialog with the server options.
 *************************************************************************/
 void popup_settable_options_dialog(void)
 {
Index: client/gui-stub/sprite.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/gui-stub/sprite.c,v
retrieving revision 1.1
diff -u -u -r1.1 sprite.c
--- client/gui-stub/sprite.c    23 Mar 2005 17:56:54 -0000      1.1
+++ client/gui-stub/sprite.c    26 Mar 2005 15:25:41 -0000
@@ -57,7 +57,11 @@
   position of the source sprite will be at (0,0) in the new sprite, and
   the new sprite will have dimensions (width, height).
 
-  mask gives an additional mask to be used for clipping the new sprite.
+  mask gives an additional mask to be used for clipping the new
+  sprite. Only the transparency value of the mask is used in
+  crop_sprite. The formula is: dest_trans = src_trans *
+  mask_trans. Note that because the transparency is expressed as an
+  integer it is common to divide it by 256 afterwards.
 
   mask_offset_x, mask_offset_y is the offset of the mask relative to the
   origin of the source image.  The pixel at (mask_offset_x,mask_offset_y)
Index: client/include/pages_g.h
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/include/pages_g.h,v
retrieving revision 1.1
diff -u -u -r1.1 pages_g.h
--- client/include/pages_g.h    18 Oct 2004 23:52:54 -0000      1.1
+++ client/include/pages_g.h    26 Mar 2005 15:25:42 -0000
@@ -26,9 +26,6 @@
   PAGE_GAME            /* In game page. */
 };
 
-/**************************************************************************
-  Does a toplevel window page transition.
-**************************************************************************/
 void set_client_page(enum client_pages page);
 
 #endif  /* FC__PAGES_G_H */