[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 23:48:11
[Download RAW message or body]

Antonio Larrosa Jim=E9nez wrote:
> =

> Peter Putzer escribi=F3:
> >
> > >
> > > - 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 documen=
ting
> > 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.

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-inclu=
de.html
but the output of current versions of doygen look much nicer than
this example would suggest.

> =

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

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

- Not invented here

There are some real issues with this:

  - How willing are the doxygen authors to work with us?

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

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


Could we hear some more opinions on this subject as this will affect
a lot of people.

Rich.


> Greetings,
> =

> --
> Antonio Larrosa Jimenez
> KDE core developer
> antlarr@arrakis.es        larrosa@kde.org
> http://www.arrakis.es/~rlarrosa
> KDE - The development framework of the future, today.

-- =

     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]