[Date Prev][Date Next][Thread Prev][Thread Next]
[Date Index]
[Thread Index]
- Subject: RE: Docstrings and interactive module help
- From: Thijs Schreijer <thijs@...>
- Date: Thu, 21 Mar 2013 08:49:39 +0000
> -----Original Message-----
> From: lua-l-bounces@lists.lua.org [mailto:lua-l-bounces@lists.lua.org] On
> Behalf Of Dirk Laurie
> Sent: donderdag 21 maart 2013 9:27
> To: Lua mailing list
> Subject: Docstrings and interactive module help
>
> 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.
From the description you're providing it seems you need to be in the function (cursor location or whatever). Is that useful? The type of help you want is generally when using a function, which almost always is in some other piece of code. And to make that work reliably, it would require type inference and the likes (the whole static analysis stuff Steve has been working on).
Thijs
