[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-23 1:13:15
[Download RAW message or body]

Stephan Kulow wrote:
> =

> Richard Moore wrote:
> >
> > 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 re=
ad, 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 litt=
le
> > > 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.

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.

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

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

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

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

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

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

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

AFAIK both kdoc and doxygen only support a subset of the above, but
for me these are the targets to aim for. I have a bunch of other
requirements too of course, but both kdoc and doxygen provide them
already.

Cheers

Rich.


> =

> Greetings, Stephan
> =

> --
> Frauen und Maenner passen vielleicht nicht zusammen, aber meine
> allerschoensten Schrammen habe ich mir bei diesem Duell geholt.
>                                                -- Reinhard Mey

-- =

     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]