[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Date: Sun, 9 Sep 2012 09:04:51 +0100
From: Justin Cormack <justin@...cialbusservice.com>
To: musl@...ts.openwall.com
Subject: Re: documenting musl
On Sun, Sep 9, 2012 at 5:15 AM, Rich Felker <dalias@...ifal.cx> wrote:
> On Sat, Sep 08, 2012 at 08:09:51PM -0700, nwmcsween@...il.com wrote:
>> IMO documentation should be inline with code, I've banged my head on
>> the wall countless times reading musl source wrt linuxisms, etc. a
>> good inline doc style is Rocco style literate inline documentation /
>> Donald Knuth style literate documentation. I also doubt any normal
>> inline documentation has any measurable compiler overhead.
>
> I acknowledge this would have benefits for understanding how the code
> works (the hackers' manual), but it's not a substitute for a
> standalone manual for somebody who's not trying to understand the code
> but just wants to use it. If we were not implementing standards (real
> and de facto ones) but instead newly designed interfaces, it might
> make sense to have interface contract documentation for library users
> inline with the code (or headers) and generate standalone docs from
> there. But documenting all the outward behavior of every function in
> libc is really orthogonal to musl, and POSIX has already done a fine
> job of most of it...
I assumed he meant writing the docs inline but then pulling them out
to generate the standalone docs.
eg the best place to write the note that dup2 will retry if it gets
EBUSY, which needs to go on the man page so the user knows that she
does not need to write the code to retry instead would be in dup2.c,
so it gets maintained if that race condition goes away one day (say,
just picking an imaginary example). A script can then go and pull this
into the man page generation. Its a device to keep the docs up to date
partly.
I think though that because of the relatively fixed scope of a libc
and the fact that the update process is disciplined it is less of an
issue, and anyway the main thing is to write the docs for now.
Justin
Powered by blists - more mailing lists
Confused about mailing lists and their use?
Read about mailing lists on Wikipedia
and check out these
guidelines on proper formatting of your messages.
