3 ms·

Rust libraries use comments for generating documentation and testing. Here is an example of such documentation: [1]. It is difficult to believe that this code w

Rust libraries use comments for generating documentation and testing. Here is an example of such documentation: [1]. It is difficult to believe that this code would be better without comments. At least classes and public methods should have comments (except trivial ones). [1] https://docs.rs/chrono/0.4.19/chrono/naive/struct.NaiveDateTime.html https://docs.rs/chrono/0.4.19/chrono/naive/struct.NaiveDateT...

pc86 5y ago
What is generating this HTML page? I'm always looking for something like this can help automatically generate documentation from code comments; it's very easy to get buy in for "update the docs when you update the code," much less so for "go through the comments for every piece of code you touch and double check they're still relevant." It's one of those things everyone nods at then promptly ignores. Something like this with a discrete task that can be checked on code review would help immensely, I think.
- netizen-936824 5y ago
  I'm interested to know the answer as well. I've used org mode in the past for literate programming and document generation, but I'm starting to think that generating docs from comments is also a good option. Adding a mechanism to publish the docs (maybe part of CI/CD?) would make maintenance way easier, it's something I would love to test out.
  - corysama 5y ago
    I’ve been working on a tool to do this based on a simple Python file watcher, web server and https://casual-effects.com/markdeep/ https://casual-effects.com/markdeep/ It just turns regular code into markdown code blocks and /** comment contents pass through to the markdown —> HTML pipeline. A little JS websocket and you get an auto-updating preview from any editor to any browser every time you ctrl-s. Not much time to work on it lately. But, I’ll Show HN when I put it on Github.
- brainlessdev 5y ago
  It's rustdoc: https://github.com/rust-lang/rustc-dev-guide/blob/master/src/rustdoc.md https://github.com/rust-lang/rustc-dev-guide/blob/master/src... > Rustdoc actually uses the rustc internals directly. It lives in-tree with the compiler and standard library. This chapter is about how it works. For information about Rustdoc's features and how to use them, see the Rustdoc book. For more details about how rustdoc works, see the "Rustdoc internals" chapter.
- gpm 5y ago
  `cargo doc` docs.rs runs it for every crate (rust library) uploaded to crates.io. When actually working with rust, I recommend running `cargo doc --open` semi frequently. It generates that documentation from all your dependencies, and your own code, links it all together (with search no less) and opens it in a browser. Note that it only uses doc comments, which are distinct from normal comments (/// instead of //, only allowed in certain places, //! Instead of /// to apply to the parent item instead of the next item).
bradrn 5y ago
Haskell does this as well, using Haddock [0] — e.g. all content on this page is generated from comments in the standard library: https://hackage.haskell.org/package/base-4.16.0.0/docs/Prelude.html https://hackage.haskell.org/package/base-4.16.0.0/docs/Prelu... [0] https://haskell-haddock.readthedocs.io/en/latest/ https://haskell-haddock.readthedocs.io/en/latest/

pc86 5y ago

What is generating this HTML page? I'm always looking for something like this can help automatically generate documentation from code comments; it's very easy to get buy in for "update the docs when you update the code," much less so for "go through the comments for every piece of code you touch and double check they're still relevant." It's one of those things everyone nods at then promptly ignores. Something like this with a discrete task that can be checked on code review would help immensely, I think.

netizen-936824 5y ago
I'm interested to know the answer as well. I've used org mode in the past for literate programming and document generation, but I'm starting to think that generating docs from comments is also a good option. Adding a mechanism to publish the docs (maybe part of CI/CD?) would make maintenance way easier, it's something I would love to test out.
- corysama 5y ago
  I’ve been working on a tool to do this based on a simple Python file watcher, web server and https://casual-effects.com/markdeep/ https://casual-effects.com/markdeep/ It just turns regular code into markdown code blocks and /** comment contents pass through to the markdown —> HTML pipeline. A little JS websocket and you get an auto-updating preview from any editor to any browser every time you ctrl-s. Not much time to work on it lately. But, I’ll Show HN when I put it on Github.
brainlessdev 5y ago
It's rustdoc: https://github.com/rust-lang/rustc-dev-guide/blob/master/src/rustdoc.md https://github.com/rust-lang/rustc-dev-guide/blob/master/src... > Rustdoc actually uses the rustc internals directly. It lives in-tree with the compiler and standard library. This chapter is about how it works. For information about Rustdoc's features and how to use them, see the Rustdoc book. For more details about how rustdoc works, see the "Rustdoc internals" chapter.
gpm 5y ago
`cargo doc` docs.rs runs it for every crate (rust library) uploaded to crates.io. When actually working with rust, I recommend running `cargo doc --open` semi frequently. It generates that documentation from all your dependencies, and your own code, links it all together (with search no less) and opens it in a browser. Note that it only uses doc comments, which are distinct from normal comments (/// instead of //, only allowed in certain places, //! Instead of /// to apply to the parent item instead of the next item).

bradrn 5y ago

Haskell does this as well, using Haddock [0] — e.g. all content on this page is generated from comments in the standard library: https://hackage.haskell.org/package/base-4.16.0.0/docs/Prelude.html https://hackage.haskell.org/package/base-4.16.0.0/docs/Prelu... [0] https://haskell-haddock.readthedocs.io/en/latest/ https://haskell-haddock.readthedocs.io/en/latest/