[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-core-devel
Subject:    Re: Proposal: replace KDOC with Doxygen after 2.0 (fwd)
From:       Richard Moore <rich () ipso-facto ! freeserve ! co ! uk>
Date:       2000-10-22 17:13:59
[Download RAW message or body]



Peter Putzer wrote:
> 
> On Sun, 22 Oct 2000, Richard Moore wrote:
> 
> >
> >
> > Peter Putzer wrote:
> > >
> > > OK, since we're basically past 2.0 at this point, I restate my earlier
> > > proposal to scrap KDOC for Doxygen.
> > >
> > > Oh, and if I remember the changelogs correctly, .kidl support has been
> > > implemented in the meantime :)
> >
> > Ok, issues:
> >
> > - Can we force people to use the java doc syntax? I think
> > we should.
> 
> Why? Actually I find the "LaTex" ("\command") syntax easier to read, but
> that's just a preference.

Personally I think the latex syntax sucks ;-)

The reason is to keep things consistent. Having two different
syntaxes for the doc comments is a Bad Thing IMHO.

> 
> > - Can we force people to keep their docs in the header files
> > not in the .cpp?
> 
> You can't do that now. If I choose to document something in the .cpp (not
> that I would, but just in theory), who's there to stop me?

This is a very bad idea. If people install binaries then they
will only have the headers. They will be unable to generate docs
if they are stored in the cpp files. In addition people often go
direct to the header files and read the docs there.

> 
> > - Can we automatically get cross-referencing between kdelibs
> > and Qt?
> 
> Yes.
> 
> > - Can we automatically get cross-referencing between the docs
> > for an app and kdelibs/qt?
> 
> Yes.
> 
> > Personally I find kdoc fine, but recent versions of doxygen
> > are ok too. Older versions of doxygen had buggy HTML generation
> > and poor C++ parsing (even recent ones appear to barf on large
> > but valid files).
> 
> And older versions (maybe even current ones, haven't checked in some
> time) of KDOC barfed on things like namespaces.

True, as I said I don't have any problem with doxygen - I
am using it for a project myself at the moment. It is worrying
though that it cannot handle a 1.2Meg source file properly (the
file contains embedded data files) this implies some O(n^2) code
in the parser to me.

> 
> > I don't really see too many gains from shifting to doxygen
> > though, what features does it support that are missing in kdoc?
> 
> It supports so many more things, I can't list them all.
> 
> Among others: nice inheritance/use graphs, better support for documenting
> enums, easy implementation docs (source-browser, ...)
> 
> http://www.stack.nl/~dimitri/doxygen/features.html#features
> 
> lists some more.
> 
> I've personally used it for a semi-large project (adding
> control-flow-graphs to the free Java compiler "guavac"), and it served us
> quite well.

The graphs are nice and I like the syntax highlighting of the
marked up header files. I can't say I've found anything else
that makes it noticably better.

> 
> Also, the author is very responsive, and if there's a critical feature we
> need I'm sure he will be glad to implement it.
> 
> OTOH KDOC is not what I would call robust, advanced C++ features easily
> confound the parser...

True, though I haven't tested doxygen with any advanced C++
features either.

Rich.

> 
> bye,
> Peter

-- 
     Richard Moore		rich@ipso-facto.freeserve.co.uk
http://www.macromedia.com/	rjmoore@macromedia.com
http://developer.kde.org/	rich@kde.org

[prev in list] [next in list] [prev in thread] [next in thread]