[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:       Peter Putzer <pputzer () edu ! uni-klu ! ac ! at>
Date:       2000-10-22 21:07:56
[Download RAW message or body]

On Sun, 22 Oct 2000, Richard Moore wrote:

> 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.

You're right on that. There is no switch or anything to ENFORCE one or the
other AFAIK, but I guess it would be easy to add...
 
> > 
> > > - 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.

You're correct, but neither doc-tool stops you from doing it. In addition,
generating meaningful (split into the libraries) documentation from
INSTALLED headers is impossible anyway!

> 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.

Of course we need to test before switching (and fix - or get the author to
fix - any problems we encounter), but I haven't yet had problems with
doxygen, on the same files that I HAD problems with KDOC (that's why I
switched to doxygen in the first place).
 
> > 
> > > 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.

It didn't break completely on namespaces (yeah that's just one thing, but
it was critical for the stuff I used).

Oh, and I love the source-browser & graph stuff, but that's just bonus.

> > 
> > 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.

Templates and namespaces, those broke with KDOC, therefore I went in
search of a better doctool => I arrived at doxygen *smiles*

Of course it has defects itself, as every software has, just less than
KDOC IMHO.

bye,
Peter

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