Re: [Libclc-developers] Suggested documentation format

[<bo...@me...>]

Hallvard B Furuseth wrote:
> Bjørn Augestad writes:
> 
[snip]

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


We can preprocess the headers when we build the documentation. A simple 
sed command can remove the clc_ prefix on argument names. That also 
solves the clc_assert problem. Not the best solution, I agree.


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

Have a look at http://www.metasystems.no/metalib/. This site is 
generated by Doxygen. It is rather old and has lots of bugs, I never get 
around to finish it. :-( Still it illustrates that Doxygen does generate 
what you're missing (if I understood you correctly).

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

Yep. ;-)

[snip]


> 
> 
>>We don't have to use Doxygen, but IMO we need a structured format for 
>>the documentation and tools to convert the  doc to the proper output 
>>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.

Well, Doxygen creates latex *plus* a Makefile which generates lots of 
other formats, including pdf, dvi and ps. ;-)

Of course, if you have a working program which provides us with what we 
need, I have no objection to using that instead of Doxygen. I just think 
that it might be better to use an existing program instead of inventing 
yet another toolset, if that's what we have to do.


-- 
boa

libclc home: http://libclc.sourceforge.net