Our great sponsors
-
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
-
Lua
Lua is a powerful, efficient, lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description.
OTOH, source-code-generated-docs normalize how code docs are, like the rust docs.rs paradigm, so it sort of forces or encourages package creators/maintainers to write docs.
doc.rust-lang.org/book: More of a "guides" thing than a source-code doc thing.
I think Lua is a good example of doing documentation well. The source code is commented only as much as needed, mainly with brief comments about things that might not be obvious and a small number of longer explanations of how the architecture works (mainly relevant to developers). It also has a super nice feature that's surprisingly rare: each file has a very short line at the top that describes what the file is, so you don't have to guess based on the filename alone. The API is documented in a single HTML file on the website that has both the high level descriptions of the language and architecture, as well as documentation for each public-facing function. The docs are maintained by hand, but the API is mostly stable, so the docs don't need to change very often.