How do you like code documentation inline in the source code vs. as separate guides, or how would you do it?

• docs.rs

  31 909 0.0 Rust

  crates.io documentation generator

  

  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.

• book

  166 13,288 5.9 Rust

  The Rust Programming Language

  

  doc.rust-lang.org/book: More of a "guides" thing than a source-code doc thing.

• Onboard AI

  getonboard.dev

  sponsored

  Learn any GitHub repo in 59 seconds. Onboard AI learns any GitHub repo in minutes and lets you chat with it to locate functionality, understand different parts, and generate new code. Use it for free at www.getonboard.dev.

  

• Lua

  27 7,491 0.0 C

  Lua is a powerful, efficient, lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description.

  

  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.

Suggest a related project