Re: documenting musl

[Rich Felker <dalias@aerifal.cx>]

On Sat, Sep 08, 2012 at 08:09:51PM -0700, nwmcsween@gmail.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