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.