Docstrings and interactive module help

[Dirk Laurie <dirk.laurie@...>]

2013/3/12 steve donovan <steve.j.donovan@gmail.com>:

> On a slight tangent, it comes up occasionally [parenthetic opprobrious
> personal remark deleted] that it would be very useful to have
> interactive help for modules. We don't have the docstring mechanism
> and tend to rely on the kind developer actually putting useful
> comments in front of functions

I append a file containing a function called "help". It extracts the
docstring from a function, the `help` field from a table or a topic
string from a predefined table of topics.

Did I say docstring? The attachment also contains a function called
"docstring". In deference to LuaDoc, this function is based on a pattern
that matches a line starting with exactly three hyphens, followed by any
number of lines starting with at least one hyphen. Those lines need to
be comments, so actually start with at least two hyphens.

`help` makes an effort to find the source code. The present version
wants the docstring to be inside the function, since for functions
loaded by `load` that is the only place it can be. Maybe the maintainer
of LuaDoc can meet me halfway: if LuaDoc is willing to look for the
docstring immediately after the function header, `help` could look for
it immediately before the function header when the code comes from
a file.

Attachment: help.lua
Description: Binary data