Follow @Openwall on Twitter for new release announcements and other news
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Sun, 9 Sep 2012 00:15:58 -0400
From: Rich Felker <dalias@...ifal.cx>
To: musl@...ts.openwall.com
Subject: Re: documenting musl

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

Rich

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.