Re: [Libclc-developers] Suggested documentation format

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

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

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

It's usually written in the header file. Those files tend to look a bit 
odd, esp. if we write a lot of documentation. ;-)

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

[snip]

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:

/**
  * @brief One line description
  *
  * The long description goes here and can span multiple lines.
  *
  * @par Example
  * @code
  *    Example C code goes here
  * @endcode
  *
  * @param  Describe parameters if applicable
  * @return Describe what the function returns
  * @see    Add references if applicable
  * @author Who wrote it.
  */
char* clc_strdup(const char* src);

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.

A real world example, borrowed from clc_string, is:
/**
  * @brief copy limited string and return pointer to end
  *
  * clc_strendcpy() copies the string src to dst, truncates it if
  * the length is >= end, and null-terminates it.
  * Nothing is done if dst >= end.
  *
  * @param  dst Destination string
  * @param  src Source string
  * @param  end You tell me ;-)
  *
  * @return clc_strendcpy() returns a pointer to the terminating null
  * character in dst, or to end (i.e. one past the null) if the string
  * was truncated. It return dst if dst >= end.
  *
  * @par Example
  * @code
  *     char buf[80], *end = buf + sizeof(buf);
  *     char *dst = clc_strendcpy(buf, str1, end);
  *     dst = clc_strendcpy(dst, str2, end);
  *     if (dst >= end)
  *         warning("string was truncated");
  * @endcode
  *
  * @see clc, strcpy, strncpy, clc_strlcpy, clc_stpcpy
  *
  * @author Howard Chu
  */
char *clc_strendcpy(
     char *dst,
     const char *CLC_RESTRICT src,
     const char *end);

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

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

It's almost time do decide on this issue, since it is blocking lots of 
other things like the release of the clc_string module and a proper 
introduction to Regis' clc_bitset.

Opinions very much wanted. :-)


-- 
boa

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