Re: Documentation

[Neil Jerram]

>>>>> "Neil" == Neil Jerram <address@hidden> writes:

    Neil> Any thoughts on appropriate syntax for documenting values
    Neil> and bindings?  In other words the analog of, in Emacs Lisp:

I think I may have just suffered a moment of clarity :-)

I just realized that, notwithstanding Scheme's emphasis on values as
opposed to names, documentation is almost always about names, aka
interfaces, aka bindings, and only rarely about values.

For example, if I write a module that exports this -

(define (frobnicate foo)
  "Frobnicate foo by flattening its buzzles."
  ...)

- the point of the documentation is to tell the module user what will
happen if they use the procedure named `frobnicate'.  It is also true
that this documentation describes the behaviour of the procedure
value, but that is a secondary angle, I think.

This suggests that the more common docstring scenario is documenting
bindings, for which a natural pattern IMO is

(define/documented NAME
                   DOCUMENTATION
                   VALUE)

(As an aside, I have in mind that DOCUMENTATION may be just a string,
or may be a string followed by an arbitrary number of keyword/value
pairs.  There is no ambiguity because NAME is always the first
argument and VALUE is always the last.)

Given this pattern, and a binding-centric viewpoint, it follows
naturally that

(define/documented (NAME FORMALS)
  DOCUMENTATION
  BODY)

is just alternative syntax for

(define/documented NAME
                   DOCUMENTATION
                   (lambda (FORMALS)
                     BODY))

(Continuing the aside, I think it is still straightforward to
determine unambiguously what is DOCUMENTATION and what is BODY here.)

It's then a simple matter of policy :-) to decide whether we are happy
to let `define' stand for `define/documented' in either or both of the
two cases above.  (Note that, despite widespread usage, the procedural
form does violate R5RS if the BODY contains internal definitions.)

For the minority of cases where it really is a value that wants
documenting, we can use something like

(with-documentation DOCUMENTATION
                    VALUE)
==
(let ((tmp VALUE))
  (set-documentation! tmp DOCUMENTATION)
  tmp)

Regards,

        Neil