From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/1899 Path: news.gmane.org!not-for-mail From: nwmcsween@gmail.com Newsgroups: gmane.linux.lib.musl.general Subject: Re: documenting musl Date: Sat, 8 Sep 2012 21:15:47 -0700 Message-ID: <7D76BD98-236A-4CB2-BF82-ED9F559E4431@gmail.com> References: <20120908024006.GA5937@brightrain.aerifal.cx> <1CAEF50B-DAB5-4B88-9B74-0334D628B0AF@gmail.com> <20120909041558.GE27715@brightrain.aerifal.cx> Reply-To: musl@lists.openwall.com NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 (1.0) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1347164169 10328 80.91.229.3 (9 Sep 2012 04:16:09 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 9 Sep 2012 04:16:09 +0000 (UTC) To: "musl@lists.openwall.com" Original-X-From: musl-return-1900-gllmg-musl=m.gmane.org@lists.openwall.com Sun Sep 09 06:16:11 2012 Return-path: Envelope-to: gllmg-musl@plane.gmane.org Original-Received: from mother.openwall.net ([195.42.179.200]) by plane.gmane.org with smtp (Exim 4.69) (envelope-from ) id 1TAYwM-0005HO-NB for gllmg-musl@plane.gmane.org; Sun, 09 Sep 2012 06:16:10 +0200 Original-Received: (qmail 9617 invoked by uid 550); 9 Sep 2012 04:16:07 -0000 Mailing-List: contact musl-help@lists.openwall.com; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Original-Received: (qmail 9608 invoked from network); 9 Sep 2012 04:16:07 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=subject:references:from:content-type:x-mailer:in-reply-to :message-id:date:to:content-transfer-encoding:mime-version; bh=3vLUZtMbOjV9tZAuNA1vT+pzkW7TFNWckO42tfyLwug=; b=jnD3KcKwsLZ45nXN3vYW60nYgDphpByM72O73/2bxTIRkPY5eL+E6Gyhb7XlHWgike ZaDPMQR/TveZ/jzMN7qv3V5NEbjjgqREOAci9DCjsLeYcuILbAesWdP3UmOBwxILEuI0 bt0i4TevB32FQEtkFoRG2ZYvhKkwRCANBb/L4q/thL4Y6AsAw9dUMGyxHlPnEDY9kaZW ygG/590Yxmdri+n+kvu/9mEcGGhVFvGGZNZ0GfZqWaICezllfiKTPhTSnqnnMb4CEBSg p/PlRm4vxHP771EBDZmBkZB0kA4tQTcXolvIqIWjIbwVQxf69HeZ0b2nlV05hXnGjnls GgeA== X-Mailer: iPhone Mail (9A405) In-Reply-To: <20120909041558.GE27715@brightrain.aerifal.cx> Xref: news.gmane.org gmane.linux.lib.musl.general:1899 Archived-At: Posix only describes what it must do not how it does it as musl vs glibc vs a= ny other libc in my opinion anyways On Sep 8, 2012, at 9:15 PM, Rich Felker 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. >=20 > 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... >=20 > Rich