 |
lua-l archive |
|
|
||
|
On Jun 5, 2008, at 4:54 AM, Tomas Guisasola Gorham wrote:
No.A note on Graham's question. I think it would be useful to document the API despite its implementation details: in this case, the object (being it a table or a userdata) offers a set of functions (or methods) and that is what matters for a programmer which is using your module.
What I have been doing so far is treating each userdata type as a distinct entity for luadoc; that is, it produces a different html file detailing the methods for the userdata.
So, if a module foo offers a userdata bar with methods ren and stimpy, the luadoc will produce a html file for foo with a link to bar, and a html file for foo.bar with a list of the functions bar:ren and bar:stimpy.
This solution isn't always ideal; the functions listed don't discriminate between bar.ren() and bar:ren() (in which case the doc would be better to list the function/method as such, rather than just the function name), and in many cases a module will publish multiple userdata that are deeply involved with each other, and might be better served as sections within a single documentation file rather than separate files. So that would be a couple of suggestions for how it could be implemented.
Graham