Re: Documentation

[Michael Livshin]

Neil Jerram <address@hidden> writes:

>   Note that `documentation-string' replaces all the existing
>   documentation mechanisms, namely:
>     (procedure-documentation proc)
>     (procedure-property proc 'documentation)
>     (object-property object 'documentation)

cool.

> - Associate docstrings with values rather than with names.
> 
>   The mechanism above does this.  Note, however, that it is sometimes
>   the right thing to document a name rather than a value, e.g. to
>   document an exported variable whose value can be set by the module
>   user to change some aspect of the module's operation.  This is
>   achieved by documenting a symbol value:
> 
>     (document! 'case-fold-search "...")

the intention is to document a binding, right?  so the above will
document the binding in the current module named by 'case-fold-search,
and not the symbol 'case-fold-search?

> - Use of markup language, both Texinfo and others.
> 
>   These decisions are delegated to the documentation filter procedure
>   that a particular module uses.  This gives a lot of flexibility; two
>   examples are (i) deciding to tailor the format of the documentation
>   output according to the type of output port (HTML output port???);
>   (ii) ability to process semantic markup like Emacs' \\[command-name]
>   as well as display markup.

wouldn't it be good to also have the ability to set this per object,
via the meta-info?  just a thought.

> - How does snarfing as a concept relate to file loading and operations
>   like `C-M-x'?
> 
>   Given the above mechanism, the snarfing of docstring comments in
>   Scheme files can be seen as part of the documentation filter
>   processing, or as a step that is performed ahead of time in order to
>   facilitate the documentation filter processing.
> 
>   One possibility which seems quite nice to me is that the output of
>   the snarfing operation is a Scheme file consisting of a sequence of
>   `(document! ...)' expressions.  In this case, the documentation
>   filter code would simply load this file in the context of the
>   corresponding module.

gah.  (sorry!)

>   As regards `C-M-x': on a `define/documented' expression, it updates
>   both the definition and the associated documentation; on a
>   `document!' expression, it updates the documentation associated with
>   the specified value; etc., as you would expect.
> 
>   Re-snarfing a file's docstring comments requires a cache-discard
>   mechanism which is the responsibility of the documentation filter to
>   support.  `load' per se should not do anything special here;
>   however, one could imagine a load hook procedure that would cause
>   a module's documentation filter to discard its cache.

hmm.

> - How to snarf/support docstrings that appear in the expansion of
>   macro calls?
> 
>   Snarfing - no support.  Macro definitions can include
>   `define/documented' and such like.

ouch.

> - Use of Guile to write snarfing tools.
> 
>   No issue here, and I think it's a good idea.

well, yes it is.

here's a mini-proposal:

what do we really want when we say "documentation for module foo"?  I
think we really are saying "documentation for all the bindings of
module foo".

so the natural (well, probably not, as it occured to me only now)
thought is: let's use the module system.

(define (snarf-docs module-name)
  (let ((module (resolve-module module-name)))
    (for-each-exported-binding (lambda (b)
                                 (filter-docs b))
                               module)))

look ma, no scripts!  and it would handle any syntax.  and it's
simple.  and you could use it in a script that you want to run upon
installation, if you want.  and of course it doesn't have to be
confined only to the exported bindings, the above is just an example.

as long as the module system provides enough reflection, of course.
the current one does.

> Looking forward to your comments!

be careful what you wish for. ;)

-- 
In many cases, writing a program which depends on supernatural insight
to solve a problem is easier than writing one which doesn't.
                                                        -- Paul Graham