Re: documenting musl

[nwmcsween@gmail.com]

Posix only describes what it must do not how it does it as musl vs glibc vs any other libc in my opinion anyways
On Sep 8, 2012, at 9:15 PM, Rich Felker <dalias@aerifal.cx> wrote:

> 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