Autogenerated lua documentation

[bmatsuo]

The disconnect between implementation and documentation is destined to repeatedly get out of sync. Ideally documentation could be attached to the implementation and extracted by a tool. Bonus points are available to a solution that allows the lark command to be used to browse docs (possibly through an embedded interpreter).

• collect a list of documentation tools: LuaDoc, annotate, ???
• choose an existing tool or decide to hand-roll one: write a simple annotation based dsl.
• switch documentation over.
• setup generation of static HTML/Markdown.

[bmatsuo]

I found a couple potential solutions, neither project seems particularly active over the past years though:

• LuaDoc -- a comment parsing solution. It's not clear how/if this would work for functions defined in Go.
  • I could probably create lua "header" files with stub definitions and all the doc comments. That seems like it would work.
  • LuaDoc probably wouldn't need to be integrated directly into Lark initially. It seems like it could run as an external thing.
• annotate -- a decorator solution. I believe this should work fine for documenting functions written in Go. The issue becomes loading the library into the binary at compile time. The core lib is pretty small and could potentially be ported to pure Go. The support libraries vary in size but can be quite large. (edit: scratch that I believe a shared C library is required. This may be a non-starter.) (edit 2: Yes. A C library is required. I don't thing I will be porting that library 😞)

[bmatsuo]

This has made me realize that there is some difficulty in presenting third-party libs as part of the (self-contained) Lark system. The utility of a library needs to be carefully weighed against the cost of integration.

I think a simple decorator based DSL could probably work fine in this case and avoid the need to include a third-partly lib. For users, it's not clear how important a particular documentation solution is. It seems most important that the documentation is available and in a format that makes sense (particularly in regard to function signatures).

[bmatsuo]

Another desirable result from a documentation solution would be the ability to browse task documentation using the lark command. An annotation based solution seems like it would work the best for this situation.

[bmatsuo]

This issue was closed accidentally by #20.

[bmatsuo]

I've started working on a static html generator for the lua doc module. But I'm realizing that it may be simpler in this regard if #24 did not include the entire "lark.task" module in the lark.task field. I think it should just include an alias to the create() function.

There is a potential problem generating documentation recursively on nested objects/functions. It's not entirely clear how big of a problem this is. If lark.task is declared as a variable then it can be omitted from any recursive documentation gathering.