Re: gtk-doc versus doxygen

[Jacob Perkins <jap1 users sourceforge net>]

Ok, I'm using gtk-doc.  Where do I put the comments, the header file or
c file? Or should I have the same comments in both?  If not both, then
is there something I should have in the other file?
Thanks

On Sat, 2002-10-05 at 21:06, Malcolm Tredinnick wrote:
> On Sat, Oct 05, 2002 at 09:59:37AM -0500, Jacob Perkins wrote:
> > Are there any gnome policies against using doxygen for documenting
> > code?  gtk-doc does not seem to have many features, and I can't find
> 
> File bug reports about the features you want, or send mail to the
> gtk-doc list to spark some discussion. However, as mentioned below, I
> think you are wanting something from gtk-doc that it is not designed
> for.
> 
> > much documentation on the features it does offer.
> 
> True, the gtk-doc documentation is a bit lacking, but the gtk-doc list
> is pretty helpful (particularly search the archives, since a lot of
> questions will have already been answered).
> 
> > doxygen, though, has some great features, such as linking to the code,
> > showing which functions are referenced by others and what each
> > function references.
> 
> Hmmm ... looks like you are wanting to provide different documentation
> from what gtk-doc is designed for.
> 
> The gtk-doc tool is for providing user documentation of the public API.
> You are wanting to use the features of doxygen that document the
> internal implementation of your package -- i.e. something for developers
> working on your package, not for the end users. These are different
> purposes.
> 
> The public API should not need to refer to the actual implementation or
> care about functions that reference this function, etc.
> 
> I should also point out that, in general, code marked up for doxygen
> parsing is _very_ ugly to read outside of the doxygen markup. It has
> random short comments (things like /* out@*/) scattered all over the
> ship and you really have to concentrate when reading the code. This is
> not a problem with gtk-doc markup -- and that is not a consequence of
> the different goals, it's a consequence of the different markup methods.
> 
> > So, if I'm hoping to have my project included in gnome cvs, or the gnome
> > desktop, do I need to use gtk-doc?
> 
> Yes, you should. It would not be very good to suddenly introduce a
> dependency on doxygen into the GNOME build hierarchy.
> 
> Malcolm
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list
-- 
pub  1024D/57DDD9E3 2002-05-24 Jacob (Direct to Home)
<jap1 rig dyndns ws>
Key fingerprint = 1E02 A5FD 8162 4322 C674  6E67 05EB 30F1 57DD D9E3