Re: improving the Lua manual?

[Ralph Hempel <rhempel@...>]

John Hind wrote:
> I agree that the return parameters ought to be shown, but I think the rest
> of the conventions used in the manual are good, i.e. optional calling
> parameters in square brackets and type information in the text. These
> conventions can easily get overly formalistic and intimidating for new
> users. Remember that calling parameters are often polymorphic so formally
> documenting the types can get very complex.

<snip>

> nil, error = io.open(filename [, mode])

That's the form I use in my pbLua documentation. Then I describe
the parameters and the types they can have in the subsequent paragraphs.

The formal parameter names often give a really good clue
as to the allowed types. In the example above, I would
assume filename to be a string. The mode parameter could
be a string or an integer representing a bitmask so that would
need a bit more explanation.

Ralph