export documentation

[lenscas]

One thing I like about rust is how easy it is to find documentation about libraries. I also like how examples also work as tests, thus making sure that the examples keep working after code updates. Maybe its possible to work towards the same ease in teal?

For those that don't know how documentation works in rust:
Every library that gets pushed to crates.io gets downloaded by docs.rs
docs.rs then builds the documentation and hosts it. It gives the crates.io a signal on where it can find the documentation
crates.io then adds a link at a standard location to the documentation.

the documentation on docs.rs is also linked with each other. So, if I have a function that returns a type clicking on the type will always bring me to the documentation of said type, even if it is from another library. If you explore https://docs.rs/quicksilver/0.4.0/quicksilver/struct.Window.html you will probably find examples of it.

Now, I don't expect to see the same infrastructure pop up, but generating documentation is still important. I am willing to help, but I'm still learning teal, so not sure how much I will be able to do.

Anyway, here is a list of stuff related to documentation that I would LOVE to see teal adopt in some way or another.

• have syntax for doc comments. I'm guessing that this already exists for lua. I'm also thinking that these comments should be kept in the lua output but I'm not sure about that.

• have syntax to start a code block, which will be used for examples. If doc comments end up in the compiled output then its probably a good idea to also translate these.

• have a command that generates the documentation. If an type/function/whatever is found without documentation then it is still visible, That way, generating documentation is at the very least a good way to see the structure of a library/program and can even be used to search for specific types/functions.

• have a command that tries to run every example, as well as any test code. If the examples fail to compile or error in some other way (fail an assert) then it counts as a test that fails.

• documentation should try to link with the documentation of used libraries. This will require teal to read the rockspecs file and generate documentation for the libraries specified there. Which I'm not sure if it is possible. I never dug into how lua exactly handles libraries.

[hishamhm]

Thank you for the writeup! It would be really awesome to have something like this indeed.

I guess we could start with the syntax for doc comments: the usual standard in Lua is LDoc, which is based on LuaDoc, which is based on the usual JavaDoc-style syntax. LDoc hasn't been heavily maintained recently so the thought has crossed my mind that Teal could handle its documentation-generation natively as part of its tooling.

The bits that would go in the compiler would probably be preserving the comments when they are lexed and storing them in the AST. Then it would be a matter of additional tooling to extract the docs, names, types from the AST nodes and generate the documentation pages. #187 also has thoughts about this core-compiler + tooling split (which today corresponds to tl.tl + the tl driver script).