[Freeciv-Dev] (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 >


Hello

As you know the comments for the gui specific functions declared in
client/include/* are written above the actual implementations. This
produces quite a bit of redundancy. Also when you create a new
function you have to copy it all over the place.

To remove this problem I suggest that we only update gui-stub and than
use a script to update all other gui directories.

However before we can do this we have to unify the comments which
exists right now in the various files and update the gui-stub files
with the most accurate version.

The attached output should help in this regard. To interpret it's
output I explain one function here:

canvas_put_line 7
>>> function name and number of implementations found
   A=1 B=4 C=2 
>>> variant names and number of occurrences of each
   client/gui-stub/canvas.c B
>>> implementation and variant
   client/gui-ftwl/canvas.c B
   client/gui-sdl/mapview.c B
   client/gui-gtk-2.0/canvas.c C
   client/gui-win32/canvas.c A
   client/gui-xaw/mapview.c B
   client/gui-gtk/mapview.c C
  ======> conflict, detailes following
>>> status
Variant A
  +----------------------------------------------------------------------------+
  |  Draw a 1-pixel-width colored line onto the canvas.                        |
  +----------------------------------------------------------------------------+

Variant B
  +----------------------------------------------------------------------------+
  |  Draw a 1-pixel-width colored line onto the mapview or citydialog canvas.  |
  +----------------------------------------------------------------------------+

Variant C
  +----------------------------------------------------------------------------+
  |  Draw a colored line onto the mapview or citydialog canvas.                |
  +----------------------------------------------------------------------------+

You see here that B contains the most information. But actually A is
better since canvas_put_line works on all canvases.

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.

        Raimar

-- 
 email: i-freeciv-lists@xxxxxxxxxxxxx
  A supercomputer is a computer running an endless loop in just a second

compare_comments.out.gz
Description: application/gunzip