Re: improving the Lua manual?

[Jim Whitehead II <jnwhiteh@...>]

On Tue, May 19, 2009 at 1:59 PM, Ralph Hempel
<rhempel@hempeldesigngroup.com> wrote:
> 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.

This is precisely what we use for documentation of the World of
Warcraft API.  All API functions are stored as simple Lua tables that
are then expanded into function signatures.  Where necessary, details
of the specific arguments are given.  Some examples:

http://wowprogramming.com/docs/api/GetItemInfo
http://wowprogramming.com/docs/api/UnitIsDeadOrGhost
http://wowprogramming.com/docs/api/GetRaidRosterInfo

- Jim