Thoughts on self-documenting functions

["Bart Schaefer" <schaefer@candle.brasslantern.com>]

On Sep 19, 10:04am, Peter Stephenson wrote:
} Subject: Re: generals observations about completion system
}
} Bart wrote:
} > It does tend to be easier to add new completion functions than it is to
} > document them.
} 
} [...] self-documenting functions with something
} like pod, except using shell functions to strip out the bits and turn them
} into yodl, should be pretty easy.  Adding comments is usually much easier
} than fiddling with the full documentation.

I actually have a bit of experience with this, and I have reservations
about how effective it will be.

In Z-Mail, which has a shell-like scripting language with "#...\n"
comments, each function may contain a block that looks like

	#%
	# Documentation goes here
	# across several lines if
	# necessary
	#%

The zscript parser grabs those comments and uses them to generate on-line
help in the GUI.  Also, if you run `func -?' the documentation block is
printed (with the leading '# ' stripped from each line) instead of
executing the real function body.

POD's biggest advantage over this scheme is that you don't have to put a
comment character on every line, which makes editing the doc a lot easier
should you ever need to change it.  The value of that convenience should
not be underestimated; zmail was heavily customized through zscript by
each of several organizations that bought it, but I never heard of anyone
who made use of this inline doc feature. Conversely, the use of POD is
quite common.

In any case, in both zscript and POD, the support for stripping the doc
out of the function is built in to the parser.  Since I don't think PWS
is suggesting we diddle with zsh's parser, we can't avoid using comments
(any other approach, e.g., here-documents, would store the documentation
as part of the function definition when it gets loaded).  That's my first
reservation.

The second is with the idea of "generating yodl" from the text in the
comment.  That seems doomed from the start; yodl's designed to be the
source language, not the generated one, and consequently has a whole
syntactic menagerie that can't be inferred from un-marked-up text, which
is all we can expect anyone to write in a shell script comment -- no one
will want to document their functions twice, so whatever form we choose
ought to be plainly readable without preprocessing.

One thought that I had is to put the documentation into its own function,
which is then unfunction'd after the whole file has been autoloaded.  So
each file _xxx would look something like:

    _xxx_doc () {
	some sort of documentation format
    }

    _xxx () {
        the actual function
    }

    unfunction _xxx_doc
    _xxx "$@"

This way, the doc format wouldn't have to be a comment, but would still
get flushed out of zsh's memory after the file is loaded.  On the other
hand, I think redefining _xxx that way prevents taking full advantage of
memory-mapped .zwc files, which is also undesirable.  However, using a
function might let us do something clever with shell expansions to mark
up the documentation for conversion to yodl.

Anyway, no conclusions yet, just musings.

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net