From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: tantalum Newsgroups: gmane.lisp.guile.user Subject: Re: procedure docstrings / documentation Date: Sun, 24 Sep 2017 00:47:30 +0000 Message-ID: <1e719937c33feae1fae7137a88d880a1@posteo.de> Reply-To: sph@posteo.eu NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII; format=flowed Content-Transfer-Encoding: 7bit X-Trace: blaine.gmane.org 1506214092 10347 195.159.176.226 (24 Sep 2017 00:48:12 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 24 Sep 2017 00:48:12 +0000 (UTC) User-Agent: Posteo Webmail To: Guile user Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Sun Sep 24 02:48:08 2017 Return-path: Envelope-to: guile-user@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dvv5b-0002K5-12 for guile-user@m.gmane.org; Sun, 24 Sep 2017 02:48:07 +0200 Original-Received: from localhost ([::1]:36481 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dvv5g-0002Aq-JK for guile-user@m.gmane.org; Sat, 23 Sep 2017 20:48:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52894) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dvv5F-0002Aa-JO for guile-user@gnu.org; Sat, 23 Sep 2017 20:47:46 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dvv5C-0006rE-GE for guile-user@gnu.org; Sat, 23 Sep 2017 20:47:45 -0400 Original-Received: from mout02.posteo.de ([185.67.36.66]:49524) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dvv5C-0006mf-90 for guile-user@gnu.org; Sat, 23 Sep 2017 20:47:42 -0400 Original-Received: from submission (posteo.de [89.146.220.130]) by mout02.posteo.de (Postfix) with ESMTPS id 4B22820CC6 for ; Sun, 24 Sep 2017 02:47:32 +0200 (CEST) Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 3y07pq3850zypX for ; Sun, 24 Sep 2017 02:47:30 +0200 (CEST) Mail-Reply-To: sph@posteo.eu X-Sender: sph@posteo.eu X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 185.67.36.66 X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Original-Sender: "guile-user" Xref: news.gmane.org gmane.lisp.guile.user:14182 Archived-At: i don't know of common conventions, but here is what i do: * i don't repeat the procedure name and parameter names because that can be queried at run-time or automatically extracted * most of the time i write a type signature in the first line of docstrings because i find that information useful * i insert newlines to limit the text width. my editor does not wrap it while keeping indent or otherwise formats it * subsequent lines get one extra space at the beginning to offset the initial doublequote of the string literal * i use a period to mark the end of sentences, but not after the type signature or the last word * in terms of markup i stick to plaintext and indented blocks for sections. but texinfo (i think that is it?) is used in guile code as far as i know to mark variable names for example, which then get special formatting or become part of an index when the documentation is created from it here is an example of a docstring in the way i would write it currently: (define (test a b) "integer string -> integer text that describes this procedure, multiline as needed" (+ a (string-length b))) i think it is nice to have an example for calling the procedure in the docstring. "example call: (interleave (list 1 2 3) 4) -> (1 4 2 4 3)" another thing that i do for documentation in modules is that i export a binding with a predictable name, for example if the module is (my module-x) i export my-module-x-description and define it like this: (define my-module-x-description "this module helps with x. syntax quote-odd :: any ... -> list quotes each second argument starting from the first and creates a list. example: (quote-odd a b c d) -> (list (quote a) b (quote c) d) data structures file-info: ((integer:mtime . string:path) ...)") because i don't know how to add docstrings to syntax definitions, i document exported syntax in this way. > Is there any convention on content/formatting for a procedure > docstring? E.g., should I repeat the procedure name and arguments? > Should I insert newlines to maintain a certain text width? > I'm not really clear on how document is done in Guile, overall. I see > Gieser has ways to look up documention for some procedures/modules, but > it doesn't seem to pull that information from the docstring, at least > not my docstrings.