[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:51:03
[Download RAW message or body]



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


>
> Stephan Kulow wrote:
> >
> > Richard Moore wrote:
> > >
> > > 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.
> > >
> > I don't see it as disadvantage though. Some header files of ours
> > got a bit _too_ informative. Some short descriptions  in headers
> > are ok, but long texts get fast on my nerves :)
>
> I think this is more a feature request than a kdoc vs. doxygen issue.
> In any case both tools give you the option of including comments/docs
> that are not part of the generated HTML.

This can already be done with doxygen using the @mainpage and @page
commands. It may be not flexible enough for general documentation, but
I managed to write doxygen's user manual with it :-)

> If we're going to list feature requests then personally I would like:
>
> - Ability to define a global index of all qt and kdelibs, and any docs
> I add later such as my own library of reusable code.

This is not directly supported by doxygen at the moment.

> - A keyword index used to search for classes by function.

Doxygen has a separate search engine (called doxysearch) that can do this.
The memory requirements for building a search index (it is a suffix tree)
are still a bit too high for large projects. I have some idea on how to
improve this but no time yet :-(

> - A way to regenerate an individual file and retain its links to the
>   stuff you rebuilt 2 minutes ago. I guess this comes down to some sort
>   of dependency detection. It's stupid that you have to regenerate the
>   entire set of docs because you edit a single file. This facility would
>   also be a big help for tools authoring docs.

I agree that this would be nice, but this is a non-trivial change.
If you for instance inherit from a class you'd have to update
the diagrams for all base classes as well. But with some extra bookkeeping
it could be done.

As an partial solution doxygen offers a tag file mechanism, where you
can compress the link information of a set of sources into a single file and
than include that with other projects (much like a library is used to
combine objects and speedup linking). This way you only have to update
the part of the docs belonging to your own sub-project. One of things
I'd still like to do is change the tag file format to XML.

> - An extensible way of finding code that uses a particular class.

This is already done for functions (when SOURCE_BROWSER is set to YES),
but it is not yet perfect.

> - A way to cleanly document a set of classes as a functional group to
>   create pages like the 'structure index' in the Qt docs. This should
>   also tie in with my next request.
>
> - A way to provide one (or more) file which provides information about
>   a group of classes - this may be be an entire library, a group of
> related
>   libraries or simply a group of related classes. I don't care if this
>   is in a dummy header, an HTML file in the source (and some magic
>   elsewhere to define the group of classes) or whatever. The important
>   thing is that these docs should be properly integrated with the
>   generated docs.

Doxygen has the @defgroup and @ingroup for this purpose. You can put
the group description in a @defgroup comment block in a file somewhere.

> - A way to include extra (non-generated) files in the docs. Assuming
>   these would remain separate this would fix the issue Coolo mentions
>   too.

You could use a similar approach as Troll Tech did with their .doc files.

> - A way for other docs to reference the docs for a particular class
>   and remain portable. (Even if it means providing an install script
>   for a bunch of HTML files).

I think what you mean is provided by doxygen's tag file mechanism.
See http://www.stack.nl/~dimitri/qdbttabular/doc/html/hierarchy.html
for an example that links to the Qt docs. The "install script" is
generated by doxygen and written in perl.

> - A way to provide external metadata about exactly what is being
>   documented. Doxygen for example has a full C pre-processor, so
>   I would like to know what symbols were defined etc. when the
>   docs were made.

Could be added.

Regards,
  Dimitri

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