Re: [Libclc-developers] Suggested documentation format

[Hallvard B F. <h.b...@us...>]

Bj=F8rn Augestad writes:

[I'm moving the bottom paragraph to the top, since this answer
got rather longer than I intended.  Sorry about that.]

> BTW, there seems to be a lot of confusion about doxygen. We don't have
> to tag everything and we don't have to write the documentation in the
> source/header files. Doxygen will process any file we ask it to
> process.  ;-)

That sounds better than clc_bitset.dox.  Maybe you can make an example
of an input file which documents a few functions, is as simple as
possible, and puts all the documentation in just one output file, like I
suggest below?  Unless, of course, you disagree that this is desirable.

> Your suggestion give me the impression that you have done this before.=20

Not really.  I have just struggled with poor user-written documentation
and ended up with some firm opinions about and how _not_ to do it, and
by implication how to do it: *Keep the format as simple as possible*.
As few format strings and special characters as possible.  Simple and
fairly rigid structure - the simpler the better.  (The doxygen variant
of that would be to use only a subset of Doxygen, and maybe write a
program which warns about deviations from this format.)  Have a program
most contributors can run which will generate a result they can inspect
and give warnings about things they did wrong.  A simple template to
fill in.  Etc.  I'm sometimes undecided about just what 'simple' means,
though: e.g. is it 'simpler' that my format says that an all-uppercase
one-line paragraph is a section header than it is to require a '@section
<section-name>' command?

Incidentally, I think some details about src/bitset/clc_bitset.dox are a
fine example of how _not_ to do it, though perhaps you were
demonstrating doxygen features rather than making nice documentation:
group__clc__bitset__card.html uses different formats for the
documentation of different functions (i.e. with/without Parameters and
Returns: sections).  A more rigid doc format would make it harder to
make that mistake.  And it splits the info in too many .html files
(maybe that can be changed?), when one single file documenting Bitset
would be more convenient.
BTW, one bug: The documentation lacks '#include <clc_bitset.h>'.

> If so, have you previously evaluated tools and formats like Doxygen
> and DocBook?

No.  I just started loosely with Pod format and reduced it further.
About Doxygen, I've looked at clc_bitset.dox and its output and didn't
like either, that's about all.  I've already covered the input format.
For the output format, personally I prefer documentation which is
structured more like manpages than the output from clc_bitset.dox.  For
example, describing many functions' parameters in one lump, and return
values (and error codes) in one lump each.  Maybe that can be fixed, if
Bertrand agrees.

> My personal experience is that Doxygen will give us most or everything
> of what we need, but I have no experience with neither SGML nor
> DocBook.

SGML is not a single format; it's the DTD you use which matters.  I
don't know DocBook.  It's SGML/XML, though.  So I vote against them:
SGML is not something the contributor should have to write, nor should
he have to download and install SGML or DocBook software in order to be
able write documentation.

> If Doxygen does what we need and is widely used, well documented and
> mature, do we need our own format and toolset?

I don't know Doxygen, but
- I think clc_bitset.dox's formatting looks more complex and free-style
  than contributors should need to deal with.  Maybe it helps if you
  don't have to stuff the documentation in a C file.
- I like to have an idea what the documentation I write will look like,
  but I'm not sure how to tell from the input documentation how the
  output documentation will be structured.  Maybe recommending a subset
  of Doxygen's features and providing a template can fix that?
- It won't give most contributors a look at the documentation they have
  produced since most won't download it.  Unless you mean for the
  documentation manager to translate all user-contributed documentation
  to Doxygen format.  I tried to think of a format that users can
  contribute (and verify) directly, and which will be as easy as
  possible for the doc manager to fix up if they blow it.

BTW, perhaps I should mention that 'my' format will need one addition
in user files: '@entry <function-name> - <one-line description>' for
each function in files that describe several functions.  And an
'@index' command in clc.* which displays the @entries and NAMEs.

--=20
Hallvard