how authors of add-on modules can package documentation

how authors of add-on modules can package documentation

[Neil W. Van Dyke]

If anyone is thinking about different ways that authors of reusable
Guile add-on modules can document their code, we should compare notes.

A year ago I kludged up a filter called "Funcelit" (as in
"functionally-illiterate programming") that extracts Texinfo fragments
from a Guile Scheme file, tweaks them a bit, and glues them together
with some boilerplate to generate a Texinfo file.

The resulting Texinfo file can be translated to Info, HTML, PS/PDF
formats using the usual Texinfo tools, but the output will be formatted
as an article rather than as a book.

Originally I had the filter treat each module as a chapter in a book,
but then I decided to focus on loosely-coupled standalone modules rather
than on a monolithic collection of modules.  Chapter formatting could be
added back in as an option.

One reason I like having full docs in the source file itself as
human-readable comments is that then a module can be shared simply by
passing around a single Scheme source code file.  This file can be
immediately viewed and modified by the person who receives it (i.e.,
there is no "tar" or package manager to deal with, no source files
getting hidden away elsewhere deep in some filesystem tree, etc.).  I
think this kind of accessibility of source files is one of the reasons
that so many people have gotten started writing their own Emacs Lisp
extensions.  Of course, a holder of a source file always has the option
of running the Funcelit filter on the source file generate pretty
Info/HTML/PS/PDF documentation.

Funcelit is not yet released, as I've been adapting it as I use it in
writing modules, and didn't want to be constantly changing the input
format on people.  I'll probably polish it up and release it not too
long after the release of Guile 1.6.

(I was reminded of Funcelit tonight because I finally kludged up some
Emacs font-lock support for Funcelit comments.  Screenshot at
"http://www.neilvandyke.org/weblog/funcelit-fontified.png".)

-- 
                                                        Neil W. Van Dyke
                                             http://www.neilvandyke.org/

_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: how authors of add-on modules can package documentation

[Evan Prodromou]

>>>>> "NWVD" == Neil W Van Dyke <nwv@neilvandyke.org> 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

Re: how authors of add-on modules can package documentation

[Neil Jerram]

>>>>> "Evan" == Evan Prodromou <evan@glug.org> writes:

>>>>> "NWVD" == Neil W Van Dyke <nwv@neilvandyke.org> 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.

    Evan> So, as a module author, I have been thinking about this quite a bit
    Evan> myself. I really, really think that there should be a "standard" way
    Evan> to write documentation for Guile, embedded into the code, as javadoc
    Evan> is for Java, or pod for Perl, or other stuff for other languages.

I haven't yet read your ideas carefully, but you might like to note
that there were a couple of mailing list threads in this area back in
February 2001:

- subject "docstring work" beginning at
  http://mail.gnu.org/pipermail/guile-devel/2001-February/001001.html

- subject "Documentation" beginning at
  http://mail.gnu.org/pipermail/guile-devel/2001-February/001154.html

I believe the consensus at the end of those threads preferred docs as
strings rather than as comments; i.e.

(define (xxx arg)
  "Do something"
  ...)

rather than

;;; Do something
(define (xxx arg)
  ...)

Oh, and don't forget i18n!

        Neil


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: how authors of add-on modules can package documentation

[Neil Jerram]

>>>>> "Neil" == Neil Jerram <neil@ossau.uklinux.net> writes:

    Neil> - subject "docstring work" beginning at
    Neil>   http://mail.gnu.org/pipermail/guile-devel/2001-February/001001.html

    Neil> - subject "Documentation" beginning at
    Neil>   http://mail.gnu.org/pipermail/guile-devel/2001-February/001154.html

Oops, and also a third thread, subject "Scheme file docstring format",
beginning at
http://mail.gnu.org/pipermail/guile-devel/2001-February/001084.html.
This last was actually the thread that started off the whole
discussion: the other two above came later.

        Neil


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: how authors of add-on modules can package documentation

[Evan Prodromou]

>>>>> "NJ" == Neil Jerram <neil@ossau.uklinux.net> writes:

    NJ> I believe the consensus at the end of those threads preferred
    NJ> docs as strings rather than as comments; i.e.

    NJ> (define (xxx arg) "Do something" ...)

    NJ> rather than

    NJ> ;;; Do something 
    NJ> (define (xxx arg) ...)

OK, but as I mentioned before, there doesn't seem to be much provision
for doc'ing variables, classes, methods, etc. with docstrings.

~ESP

-- 
Evan Prodromou
evan@glug.org

_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: how authors of add-on modules can package documentation

[Thien-Thi Nguyen]

   From: Evan Prodromou <evan@glug.org>
   Date: Sun, 17 Mar 2002 18:04:40 -0800

   OK, but as I mentioned before, there doesn't seem to be much provision
   for doc'ing variables, classes, methods, etc. with docstrings.

below is (ttn defvar).  is this what you mean?

thi

________________________________
;;; ID: $Id: defvar.scm,v 1.3 2000/09/11 01:13:41 ttn Rel $
;;;
;;; Description: Provide `defvar' and some doc-access procedures.

(define-module (ttn defvar))

(defmacro defvar (name value docstring)
  `(let ((var (make-variable ,value ',name)))
     (module-add! (current-module) ',name var)
     (set-object-property! var 'documentation ,docstring)
     ,value))

(define (documentation-property obj)
  "Return, as a string, documentation on OBJ, or #f.
OBJ may be a pair of the form (MODULE . SYM), where MODULE is in list
form as in `define-module', in which case MODULE is consulted instead of
the current-module."
  (cond ((variable? obj)
	 (object-property obj 'documentation))
	((procedure? obj)
	 (procedure-documentation obj))
	((symbol? obj)
	 (documentation-property (module-variable (current-module) obj)))
	((pair? obj)
	 (save-module-excursion
	  (lambda ()
	    (set-current-module (resolve-module (car obj)))
	    (documentation-property (cdr obj)))))
	(else #f)))

(export defvar
	documentation-property)

;;; $RCSfile: defvar.scm,v $$Revision: 1.3 $ ends here


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: how authors of add-on modules can package documentation

[Thien-Thi Nguyen]

   From: "Neil W. Van Dyke" <nwv@neilvandyke.org>
   Date: Sat, 16 Mar 2002 23:18:52 -0500

   Funcelit is not yet released, as I've been adapting it as I use it in
   writing modules, and didn't want to be constantly changing the input
   format on people.  I'll probably polish it up and release it not too
   long after the release of Guile 1.6.

if you decouple Funcelit release from guile release, people can use it
sooner.  plus, that would give everyone (especially guile maintainers)
more options when figuring out how to design "official" doc snarfing.

thi

_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel