[CF-Devel] Documenting the code, and cleaning warnings

[crossfire-devel at archives.real-time.com]

Hello.

Mark & I discussed the pros & cons of doing some code cleaning (mostly fixing 
types, like using short and not an int when a function expects a short, stuff 
like that).

The result is that he doesn't mind cleaning, as long as I (or anyone else, for 
that matter) don't break anything.
So I will slowly clean the code, and submit patches now & then.

Since I'll skim part of the code, I feel like taking the time to put a few 
comments when a function doesn't have any.
Would anyone mind if I wrote in doxygen-style? Or if I changed existing comments 
to be doxygen-usable?

Basically, the doxygen style looks like:

/**
  *   Fixes walls around specified spot
  *
  *   \param map is the map
  *   \param x
  *   \param y are the position to fix
  *
  *   Basically it ensures the correct wall is put where needed.
  *
  *   Note: x & y must be valid map coordinates.
  */
void fix_walls( struct mapdef* map, int x, int y )

First line is a brief description, rest should be easy to guess...
This can be used to make 'nice' html/latex/other format documentation.
Of course parameters & return values are not mandatory, though sometimes it's 
better to explain'em.

What does everyone think?
And no, I don't expect everyone to write comments like that, just saying I dont 
mind modifying existing ones to make documentation :)

Nicolas 'Ryo'


_______________________________________________
crossfire-devel mailing list
     
     crossfire-devel at lists.real-time.com
     
     
     https://mailman.real-time.com/mailman/listinfo/crossfire-devel