[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 21:53:13
[Download RAW message or body]

Peter Putzer wrote:
> 
> 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 you ask the author to add it? (see my other mail)

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

IIRC kdoc only processes the header files, so it is enforced. If we
could tell doxygen to ignore (or insert an error message in the
generated
docs) doc comments in the cpp files then the world would be a better
place. :-)

Generating docs from installed headers is not actually so hard. I've
done it before - the disadvantage is just that the separation between
the different kde libraries is lost. This is annoying in some ways, but
being able to view a global table of contents is actually quite nice.

I have been planning to add some code to kdoc to deal with the installed
headers situation in any case, all you need is a file that maps the
names
of the headers to the libraries they belong to. The advantage is that it
lets you generate a global contents page, index and (with some
dictionary
analysis) a keyword index. Of course, this could be implemented just as
easily against doxygen (ie. this paragraoh is for informational purposes
only).

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

Could you try to hack up a doxygen configuration for kdelibs that we
could all test? If nothing else, this would give us an idea of how
many syntax issues there are.

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

These issues annoyed me too, but they're fixed now. We really ought to
get Taj's opinion on this - after all he is the author of koc. I'll send
him a mail about this thread and ask him to comment.

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

Sure - like I said I have no great problem with changing, all I
want to do is make sure that:

- the result will be better documentation
- the documentation is accessible to as many users as possible

  A final issue with this is getting the new tool integrated nicely with
  kdevelop. Ideally we would like to have something working before the
1.3
  release which is coming RSN. I don't see any serious issues here, but
  perhaps one of the kdevelop team could comment.

- the change over will be relatively painless to developers
- fixing the developer site to use the new stuff will not be too hard
- the docs are available in all previously supported formats

Cheers

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]