[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Sat, 8 Sep 2012 20:09:51 -0700
From: nwmcsween@...il.com
To: "musl@...ts.openwall.com" <musl@...ts.openwall.com>
Subject: Re: documenting musl
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.
On Sep 7, 2012, at 7:40 PM, Rich Felker <dalias@...ifal.cx> wrote:
> Hi all,
>
> One item that's been on my todo list for a while, but didn't really
> make it into the last email, is creating some kind of documentation
> for musl.
>
> One document, which I would call simply the "manual", should cover
> everything you need to know if you're writing applications against
> musl or building existing applications against musl. It should contain
> introductory materials on the standards and extensions musl aims to
> support, feature test macros, etc. It should also document musl's
> locale behavior, quality of implementation guarantees, and anything
> ISO C or POSIX requires an implementation to document (i.e.
> implementation-defined behavior). In some cases, the documentation may
> defer to that for the compiler being used. The manual should further
> document any additional behavior guarantees for functions beyond
> what's required in the standard, as well as behavior for all supported
> non-standard functions.
>
> A second possible document would be oriented towards people wanting to
> learn from the source, port musl to new platforms, add features or
> customize it for unusual usage cases, reuse parts of musl in other
> software, etc. This document would explain the source tree layout and
> build system, use of weak symbols and object file dependency graph
> issues, stdio and pthread internal interfaces including thread
> cancellation architecture, porting requirements, and so on.
>
> For getting the documentation done, and ideal situation would be for a
> FOSS documentation guru with an interest in musl to show up and
> volunteer to organize the documentation effort, write major portions,
> and maintain it. In the absence of such a miracle, perhaps we could
> turn the above ramblings into a sort of outline for the proposed
> documentation, and use the wiki to draft unofficial documents that
> cover some of the same topics. I think the wiki would be especially
> appropriate for the developer/hacking documentation, since it's less
> official in nature and more community-oriented.
>
> Ideas? Volunteers?
>
> 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.
