Re: Thoughts on self-documenting functions

[Sven Wischnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>]

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@xxxxxxxxxxxxxxxxxxxxxxx