Re: Looking for good examples of Lua/C++ API documentation

[Frank Kastenholz <frank@...>]

> On Jan 3, 2021, at 3:55 AM, watusimoto <watusimoto@bitfighter.org> wrote:
> 
> Hi,
> 
> I'm reworking the documentation for the open source game Bitfighter (bitfighter.org), which uses Lua scripting to support a number of different functions.  I'm having trouble conveying the information I want, and am looking for good examples of effective Lua API documentation.
> 
> My specific issues are how to express argument and return types, as Lua does not have a natural way to do this (documenting C++ or Python functions is much easier in this regard).  I know what information I need to show, but not how to show it.
> 
> Pointers to good examples would be most welcome.
> 
> Thank you!
> 
> Chris

In the Lua work I do I tend to use a hybrid C/Lua form, where each argument & return value has a “type” and name.

Types generally are the Lua types (“string”, “boolean”, and so on). If a type is a table, it might simply be “table” or, if the table has a specific type (even if that ‘type’ is not a formal Lua type) we might refer to it as a “foo_table” or “foo_t”.  If the table is strictly a list of somethings, we might refer to it as “number xxx_list” or “number xxx[]”. A user datum would be “user data” or “blah_ud” or “blah_user_data”.

Multiple return values are something like “number return_value1, string return_value2 = somefunction(…)”

… has the usual meaning

If I have an argument or return value that can be different types, it would be something like  
   func(integer int_arg | string string_arg)
With | denoting “or”

If a function has so many different call or return signatures that can not be easily captured by optional arguments or arguments having different types, I just describe it multiple times, 

Optional arguments or return values are surrounded by [].  string.format() would be
Described as
     string result = string.format(string format_spec[, …])


I tend to use a similar technique for describing tables as well. Eg, if there is a fubar table
With a bunch of different fields I might describe it as

fubar_table = {
    integer  integer_field,
   number number_field,
   string string_field1,
   [string optional_string_field_2,]
}
And so on

This misses a bunch of corner cases in Lua - but it does cover the vast majority of
The stuff I do.  For those odd cases I can’t describe cleanly or easily I just use more text.

I don’t have a formal, rigorous, grammar, this is strictly meant for humans to read so any inconsistencies
or potentially conflicting interpretations are handled by adding explanatory text.

I do not have any public examples I can point you to, sorry.

Frank