Re: Implementing help function (like in Python)

[Daniel Silverstone <dsilvers@...>]

On Fri, 2007-09-14 at 22:22 +0100, Daniel Silverstone wrote:
> I added docstrings to the Lua interpreter embedded in Aranha and set
> about writing parsers and help formatters.

It struck me that I ought to include some basic notes on it...

The docstrings are delimited by the -=- token and must be the first
thing in a chunk.

For C functions there is doc.setdoc which can set the magical docstring
attribute on a function, table or userdata.

As an example, here's the top of the constructor for the aranha.request class:

   function :Constructor(env, inputstream, outputstream, errorstream, flush)
      -=-
      Construct a request

      Provided with an environment, a way to get at the input stream, output
      stream and error streams of the request and a way to flush the output
      and error streams if needed.

      @param env(table) The environment for the request
      @param inputstream(function) Function to return the input stream
      @param outputstream(function) Function to write to the output stream.
      @param errorstream(function) Function to write to the error stream.
      @param flush(function) Function to flush the output and error streams.
      -=-

and something which returns stuff:

function argumentGatherer(t)
   -=-
   Construct a table and argument gathering routine.

   This constructs an empty table and returns it, along with
   a function which when called appropriately adds an element
   to the argument table according to the algorithm which
   aranha puports to implement for cookies, CGI params etc.

   @param t(table,nil) A table to augment with the values gathered.
   @return (table) The table into which the arguments will be gathered.
   @return (function) Takes a name and a value and stores it into the argument table.
   -=-


-- 
Daniel Silverstone                         http://www.digital-scurf.org/
PGP mail accepted and encouraged.            Key Id: 2BC8 4016 2068 7895