Re: Comments in code

["Marcus Hast" <marcushast gmail com>]

Hi all,
Hope you've had a good holidays.

Stephane:
Sorry if I came off as a bit argumentative before. I just feel that
it's an important topic and when I first dove into the F-Spot code I
was a bit dismayed that there was no comments. Comments on Classes and
Methods would go a pretty long way. (And a good start is to simply add
comments on new code.)

But having a solid comment standard makes it all more useful.

> I don't know if Mono supports it, but MS's C# compiler allows for
> xml-structured comments for classes and functions, for example:
>
> ///<summary>
> /// Does x for y iterations
> ///</summary>
> ///<param name="y">The number of times to do x</param>
> public void DoX (int y) {...}
>
> If we used that, then (supposedly) we could easily generate code documentation.

I haven't used that style before but I have to say it seems very
convoluted compared to eg Javadoc style.

And example of Javadoc style is as follows:
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute { link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param  url  an absolute URL giving the base location of the image
* @param  name the location of the image, relative to the url argument
* @return      the image at the specified URL
* @see         Image
*/

One tool which can parse Javadoc style comments and generate
documentation is Doxygen. It seems like there are also MonoDoc and the
mono compiler can be executed with "mcs /doc" to generate
documentation.

Using tools to generate docs from the source is a really good idea in
my experience. Besides the obvious of having documentation it's really
nice to have access to a API of the program for when you are coding.

Though I have to say that in general I find the code in F-Spot to be
easy to read and understand. So the need for documentation isn't as
critical as in other code bases I've seen.

/Marcus Hast