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 [EMAIL PROTECTED] 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
_______________________________________________
F-spot-list mailing list
[email protected]
http://mail.gnome.org/mailman/listinfo/f-spot-list
