Re: grace period [ was developers' guide]

[Nadim Shaikli <shaikli at yahoo dot com>]

--- Mohammed Sameer <uniball at gmx dot net> wrote:
>
[snip snip]
>
> > > doxygen ? I don't think that's required if I'm not writing a library.
> > 
> > The Doxygen requirement is only there to force commenting the code. The
> > comments should be done using the Doxygen style comments.. which are
> > fairly easy and flexible. No one is required to use all the features
> > that come with Doxygen (they are pretty elaborate). Simply commenting
> > each and every function at a minimum.
>
> I have a suggestion here:
> I'm using Gtk, I think using gtk-doc 'd be better than doxygen
> Another developer is using Qt/Kde, then use their documentation 
> framework.
> etc...
> Only use doxygenn if No documentation framework is there for the toolkit 
> used/or if you are developing a console application.

This is the one item that doesn't gimme the warm-n-fuzzies.  I always
comment my code enough for me to remember what the heck I was trying to
do (and that is no easy task for my wrapped brain), yet I'm uneasy about
having a "framework"/system in place that tells me how I should do it - I
also know ZERO about doxygen (and thus the uneasiness), but we all learn
and if its a must, I can certainly give it a try at a min to have a better
stance in the future :-)  I think the intent here is to have the source
code commented to some degree (in case people disappear and someone else
needs to pick up), but I don't think doxygen will guarantee the quality
of those comments.  I also think most (if not all) applications should have
an accompanying 'man' (ie. manual) page (ie. application.1) geared towards
the end-user and not the developer necessarily.

Just some thoughts.

Salam.

 - Nadim

__________________________________
Do you Yahoo!?
Yahoo! Mail SpamGuard - Read only the mail you want.
http://antispam.yahoo.com/tools