|
Date: Sun, 9 Sep 2012 00:15:58 -0400 From: Rich Felker <dalias@...ifal.cx> To: musl@...ts.openwall.com Subject: Re: documenting musl 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.