Re: [Libclc-developers] Suggested documentation format

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

Bj=F8rn Augestad writes:
>Hallvard B Furuseth wrote:
>>Bj=F8rn Augestad writes:
> [I snipped a lot here, hope that's OK]

Snipping is good.

>> 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.
>=20
> It's usually written in the header file. Those files tend to look a bit=20
> odd, esp. if we write a lot of documentation. ;-)

Then attribute names in the documentation will all start with 'clc_',
because of namespace issues.  That's not good.  And we'd also have to
start all parameter names in the .c files with 'clc_', so that parameter
names in clc_assert_arg() would match those in the documentation.

> I'm currently using Doxygen a lot at work these days and will
> hopefully learn the finer details about Doxygen within the next month or
> so. This means that I can provide a good template later. The template I
> use at work right now is approximately this:

Thanks.

> In addition to this I use a file section which in our case could be a
> module description. I will in some cases use grouping as well, which
> probably is the most confusing concept from clc_bitset.dox. The syntax
> for grouping is not the best, IMHO.

Nor is the navigation possibilities in the resulting files, unless you
can generate an index over which functions are documented in which
files, and a one-line file description for each file which the index
page describes.  At least that's my impression from the documentation
generated by bitset.dox.

> This untested example has a lot of structure, but is fairly easy to use,=
=20
> IMHO.  I vote for something like the example above. ;-)

Well, you know my vote:-) It's all very nice to have the documentation
together with the source, but it has its small troubles, and I also like
better control over what the documentation will look like.  Also it gets
more verbose:  One can't include a single section like
    RETURN VALUE
        These functions return the dest parameter.
Instead this gets repeated for each function description.

> We don't have to use Doxygen, but IMO we need a structured format for=20
> the documentation and tools to convert the  doc to the proper output=20
> formats (html, man, latex, Windows help, RTF, others?).

Yes that's nice.  My program can only generate html, man and text.
I could probably add latex, but I'd have to learn it first.

Other formats: Plaintext and PostScript.  Groff can generate both from
the manpages.

--=20
Hallvard