Follow @Openwall on Twitter for new release announcements and other news
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Sat, 8 Sep 2012 21:15:47 -0700
From: nwmcsween@...il.com
To: "musl@...ts.openwall.com" <musl@...ts.openwall.com>
Subject: Re: documenting musl

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