From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Evan Prodromou Newsgroups: gmane.lisp.guile.devel Subject: Re: how authors of add-on modules can package documentation Date: Sun, 17 Mar 2002 10:41:04 -0600 Organization: GLUG (Guile Lovers Use Guile) http://www.glug.org/ Sender: guile-devel-admin@gnu.org Message-ID: <87zo17f8pr.fsf@tyrell.bad-people-of-the-future.san-francisco.ca.us> References: <15508.6444.70455.739266@winona.neilvandyke.org> NNTP-Posting-Host: localhost.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1016383382 19119 127.0.0.1 (17 Mar 2002 16:43:02 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Sun, 17 Mar 2002 16:43:02 +0000 (UTC) Original-Received: from fencepost.gnu.org ([199.232.76.164]) by main.gmane.org with esmtp (Exim 3.33 #1 (Debian)) id 16mdkL-0004yA-00 for ; Sun, 17 Mar 2002 17:43:01 +0100 Original-Received: from localhost ([127.0.0.1] helo=fencepost.gnu.org) by fencepost.gnu.org with esmtp (Exim 3.34 #1 (Debian)) id 16mdjS-0007kH-00; Sun, 17 Mar 2002 11:42:06 -0500 Original-Received: from tl3-20-254.tca.net ([208.180.20.254] helo=tyrell) by fencepost.gnu.org with esmtp (Exim 3.34 #1 (Debian)) id 16mdjM-0007jy-00 for ; Sun, 17 Mar 2002 11:42:00 -0500 Original-Received: from evan by tyrell with local (Exim 3.34 #1 (Debian)) id 16mdiW-0000cz-00 for ; Sun, 17 Mar 2002 10:41:08 -0600 Original-To: guile-devel@gnu.org X-PGP-Fingerprint: 1366 538C 1E7D 0093 C45B 1A50 A33C 1E7C 700A 0551 X-Revolutionary-Date: Septidi, 27 Vento^se 210 4:17:97 -29167 In-Reply-To: <15508.6444.70455.739266@winona.neilvandyke.org> ("Neil W. Van Dyke"'s message of "Sat, 16 Mar 2002 23:18:52 -0500") Original-Lines: 90 User-Agent: Gnus/5.090005 (Oort Gnus v0.05) Emacs/21.1 (i386-debian-linux-gnu) Errors-To: guile-devel-admin@gnu.org X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.0.5 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: Developers list for Guile, the GNU extensibility library List-Unsubscribe: , List-Archive: Xref: main.gmane.org gmane.lisp.guile.devel:97 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:97 >>>>> "NWVD" == Neil W Van Dyke writes: NWVD> If anyone is thinking about different ways that authors of NWVD> reusable Guile add-on modules can document their code, we NWVD> should compare notes. So, as a module author, I have been thinking about this quite a bit myself. I really, really think that there should be a "standard" way to write documentation for Guile, embedded into the code, as javadoc is for Java, or pod for Perl, or other stuff for other languages. There should be a tool to extract that documentation automatically to static formats, such as (as you said) texinfo, plus a *roff file for man pages. In addition, the documentation should be available in Guile interactive sessions through the (help) facility or something like it. A user shouldn't have to care whether a function was defined in guile-core or by Evan Prodromou when asking for (help). In any system, function signatures should be grabbed automatically for basic function definition formats [(define (foo x) ...), (define-public (foo x) ...), (define foo (lambda (x) ...))]. This should be axiomatic. I'd personally like to see GOOPS (define-class) and (define-method) stuff grabbed automatically, too, but that's just me. The hard part is getting description documentation -- the author's description of what a function does, what it's for, what it returns, and what to look out for, etc. This is a little harder to figure out where it is and what it's related to. I think there are several ways to have embedded documentation: 1. The traditional Lispy ; commenting style. Old-schoolers know that a four-semicolon comment (;;;;) introduces a description of the file in general, three semicolons (;;;) is a per-definition (function or variable) description, two semis (;;) for a comment on its own line and one semi (;) for an in-line comment. It would be relatively easy for a text processor to grab foursies to make them the file description, and threesies to associate them with the next variable or function. It'd be kind of hard to do for interactive sessions, however, since normally comments are, after all, thrown away. Also, there's a big problem with false positives, as not all programmers follow this practice. 2. The documentation string. This is also pretty traditional for Lispers, and it's a simple enough way to put in a description of whatever format and length. I think the problem with docstrings is that there's not really a good way to attach one to a file or to a variable, much less to a GOOPS class or method. So any embedded overview, or details for non-function interface items, are lost. 3. "Special" comments or structures. These would be new Guile-specific mechanisms, like, say: ; {doc-comment} ; {/doc-comment} Or even (define-documented (func #:desc does something #:throws bounds-exception (x #:desc first param) (y #:desc second param))) I think that this would probably be easiest to process, but would require a lot of hassle for the author. Of these three, I like the semi-colon format the best, but I dunno. Regardless of how it's done, I think a Suggested Documentation Format is something that's going to have to happen sooner rather than later, or diverging de facto stuff will happen (or, worse, no documentation at all). ~ESP P.S. As to man pages: I think a suggested module.3guile is imperative. Man pages make the world go round, after all, and I don't think texinfo puts them out. -- Evan Prodromou evan@glug.org _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel