Re: Thoughts on self-documenting functions

Re: Thoughts on self-documenting functions

[Sven Wischnowsky]

Bart Schaefer wrote:

> ...
>
> 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 "$@"

Sounds interesting, but...

> 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. 

yes, I'd say.

> 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.

Some time ago we were discussing (well, not really discussing, but I
mentioned it, I think) this kind of automatic documentation for the
completion system already. At that time I played a bit with such
special comments Bart described. Because I would like those comments
to be enough to automatically generate the docs I needed to make it be 
converted to yodl. I used some convention, like `foo' being turned
into `tt(foo)' and things like that, trying to keep the work load for
the function writer low. But it still was a bit clumsy.

I don't have any really good ideas either (obviously, you would have
heard about them), but I still like the whole idea of it. So that it
would allow us to 1) always keep the docs up to date, including
utility functions, 2) correctly list all tags and styles in
_complete_help, preferrably even with short descriptions 3) add a mode 
to _complete_help that displays a description like the one Peter
suggested some time ago (a real, textual description, not just a list
of things).

Bye
 Sven


--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de

Thoughts on self-documenting functions

[Bart Schaefer]

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