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

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Watusimoto
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
Reply | Threaded
Open this post in threaded view
|

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

frank@kastenholz.org


> On Jan 3, 2021, at 3:55 AM, watusimoto <[hidden email]> 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