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

List:       kde-core-devel
Subject:    FW: Proposal: replace KDOC with Doxygen after 2.0 (fwd)
From:       "Peter Putzer" <pputzer () edu ! uni-klu ! ac ! at>
Date:       2000-10-23 21:49:34
[Download RAW message or body]



-----Original Message-----
From: Dimitri van Heesch [mailto:dimitri@stack.nl]
Sent: Monday, October 23, 2000 9:34 PM
To: Peter Putzer
Subject: Re: Proposal: replace KDOC with Doxygen after 2.0 (fwd)


>
> Antonio Larrosa Jiménez wrote:
> >
> > Peter Putzer escribió:
> > >
> > > >
> > > > - 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.
> > >
> >
> > Peter, can you do a short description of the difference in the
> > "commands" ? (I've only used @p, @ref, @version, @author and a little
> > more)
> >
> > > > - 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?
> > >
> >
> > Does that mean that Doxygen doesn't allow having the docs in the
> > header files ?
>
> No, it supports docs in the header files. The only issue is if you
> can actively stop it allowing people to put their docs in the cpp
> files instead. According to Peter's other mail, the answer is yes.
>
> >
> > > 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
> >
> > Can you provide better a link to an already generated example
> > documentation from the KDE sources ? That way it would be better
> > to compare.

Doing a search for "doxygen" on the kdevelop mailing list archive gives
this:

= have a test set of Doxygen generated html files for
= KDE/QT/C++.  Currently they are on a LOW bandwidth
= link http://melchior.msoe.edu/  I will be moving
= the entire html archive as soon as the build is
= good enough (tm).
=
= Have a look and tell me what you think...
=
=        -ian reinhart geiser

So it has been done already :-)

> Good idea, I'd like to see that too. I guess the main difference
> will be the addition of class diagrams like this:
>
> http://www.stack.nl/~dimitri/qdbttabular/doc/html/class_qdbttabular.gif
>
> I guess we should aim to convert these class diagrams to pngs before
> we make a release dependent on doxygen.
> This is taken from:
>
http://www.stack.nl/~dimitri/qdbttabular/doc/html/class_qdbttabular-include.
ht
> but the output of current versions of doygen look much nicer than
> this example would suggest.

I can personally recomment to take a look at
http://xml.apache.org/xerces-c/apiDocs/index.html
It shows how doxygen can look for a real project.

> >
> > I'm in the same position than Richard here, I don't see any need
> > to change what is not broken unless it gives much better features.
> >
>
> Other features of doxygen I've liked when I've used it elsewhere are:
>
> - Easy to include/exclude files from the docs
>
> - Nice config file for a project which make generating the docs as easy
>   as typing 'doxygen'. kdoc provides a similar feature in makekdedoc.
>
> - Reliable. Even when the source code has been messy I've found doxygen
>   to be stable. The problem I cited earlier with large files is
> definitely
>   the exception not the rule.
>
> The main problems I see with changing it are:
>
> - It isn't broken. Despite previous problems, things are working ok
> right
>   now.
>
> - Does the cost out weigh the benefits?
>
> Given that Peter is willing to manage the change I think we're ok on
> this.
> I don't think the benefit is that great, but I agree with Peter doxygen
> does
> provide a powerful solution than kdoc.
>
> - Doxygen is too powerful
>
> Doxygen is a little too flexible - it allows people to make mistakes and
> get away with it. This is great for standalone projects etc., but makes
> it hard for us to maintain a consistent quality and style throughout a
> large multi-developer project like KDE. If doxgen's author is willing
> to add the ability to enforce javadoc syntax and to only accept
> doc-comments in the header files then this issue is solved.

This would be acceptable. I wouldn't even mind adding a KDE specific
conformance option if that is needed.

As a side note: I'm in the process to replace
the current documentation scanner by a real parser that builds a nice
tree structure and enforces real syntax checking. Then it would be even
easier to generate different output formats (like XML) and guaranteeing
valid output.

> - Does every kdoc feature have a doxygen equivalent?
>
> I know doxygen has more features, but this doesn't mean that everything
> kdoc can do is supported. I would guess that if any problems exist here
> then we can resolve them fairly easily.

Yes, I think doxygen should support everything kdoc does, so let me
know if I forgot something.

> - Not invented here
>
> There are some real issues with this:
>
>   - How willing are the doxygen authors to work with us?

I'm the main author of doxygen (still doing about 90% of the work). Since
my time is finite, I would really welcome some extra help. I appreciate
any suggestions for improvement, but would really also welcome patches :-)

I do have a user-base that is a bit wider that just Unix, so I would like to
keep things portable to Windows as well (Yes, it is not my choice of
OS either :-)

>   - If we want to add support for something be it a new input format,
>   output format etc. How hard will it be to get the code rolled in to
>   the doxygen tree.

Depends of course on the amount of work I would have to do ;-)  If it is
just applying a patch, then that is no problem at all.
Parker Waerchter has contributed support for RTF output, so it can and has
been done (though effort is still being done to make it much easier).

>   - Will it be possible to integrate doxygen with future tools which
>   need to use docygen as a library? I am thinking here of GUI tools for
>   editing API docs, integration with kdevelop 2 etc.

I wouldn't be harder than for kdoc, likely easier since doxygen is written
in C++ and depends on Qt only. There is already a Qt based GUI front-end for
configuring doxygen, which should not be too hard to blend into a KDE app.

>   - I think kdoc produce better looking output. It would be nice to make
>   a KDE style which could be developed by people with graphic/web design
>   experience as well as developers.

I'm open for any changes that look nice :-)

> I don't see any of these as being a major problem, but it would be good
> to hear some other opinions (especially those of the doxygen team). Are
> there any problems I haven't considered?
>
> - Updating kdevelop to use the new tool
>
> Not hard I would guess.

I just got this mail from Micha Bieber <micha@ani.de>:
= I would like it to have doxygen as standard/optional Documentationtool
= for kdevelop.
= I've done a quick hack yet, and it looks promising, but needs
= Consultation with the kdevelop guys. When you not mind, I would initiate
= this ...

Of course I do *not* mind ;^)

Regards,
  Dimitri (dimitri@stack.nl)

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