4 ms·

> The "what if you don't have the tool" situation never happens in case of Rust. So it’s built into GitLab and GitHub? BitBucket? How easy is it to use on wind

by jmb99 2y ago

> The "what if you don't have the tool" situation never happens in case of Rust. So it’s built into GitLab and GitHub? BitBucket? How easy is it to use on windows (i.e. is it is easy as opening a .h in notepad and reading it)? How easy is it to use from a command line environment with vim or emacs bindings? I could go on. “Never” is doing a lot of heavy lifting in your assertion. I shouldn’t have to install a toolchain (let alone rely on a web browser) to read API documentation.

Dylan16807 2y ago
> I shouldn’t have to install a toolchain (let alone rely on a web browser) to read API documentation. Why are you reading a library API for a language you're not coding in? I'm sure you can come up with some situation, but that situation should NOT be what we optimize for. And web browsers are fine. > is it is easy as opening a .h in notepad and reading it If you include the actual ease of reading, yeah it should be.
nindalf 2y ago
> I could go on Please do. It just sounds like you’re nitpicking. If you can open a browser, open docs.rs. The GitHub repo usually contains a link to docs.rs because that’s how people prefer to read the documentation. If you prefer working without the internet that’s fine too. Use cargo doc, which opens the rendered doc page in a local web browser. If you prefer being in a text editor exclusively, no problem! Grep for `pub` and read the doc comments right above (these start with ///). No toolchain necessary. Look, most normal people don’t have some intense phobia of web browsers, so they’d prefer docs.rs. For the people who prefer text editor, it’s still a great experience - git clone and look for the doc comments. The point is, the existence of docs.rs only encourages Rust library developers to write more and better documentation, which everyone, including text editor exclusive people benefit from. That’s why your comment sounds so strange.
- devvvvvvv 2y ago
  [flagged]
  - hooli_gan 2y ago
    Most normal people don't read documentation of programming libraries.
  - estebank 2y ago
    Most normal people don't comment on hackernews, yet here we are.
kouteiheika 2y ago
> So it’s built into GitLab and GitHub? BitBucket? No. It's built into the toolchain which every Rust developer has installed. > How easy is it to use on windows (i.e. is it is easy as opening a .h in notepad and reading it)? A easy as on Linux or macOS from my experience. > How easy is it to use from a command line environment with vim or emacs bindings? Not sure I understand the question; use how exactly? You either have a binding which runs `cargo doc` and opens the docs for you, or you use an LSP server and a plugin for your editor in which case the docs are integrated into your editor. > I shouldn’t have to install a toolchain (let alone rely on a web browser) to read API documentation. If you want you can just read the source code, just as you do for any other language, because the docs are right there in the sources. For publicly available libraries you can also type in `https://docs.rs/$name_of_library https://docs.rs/$name_of_library` in your web browser to open the docs. Any library available through crates.io (so 99.9% of what people use) have docs available there, so even if you don't have the toolchain installed/are on your phone you can still browse through the docs. I know what you're going to say - what if you don't have the toolchain installed and the library is not public? Or, worse, you're using a 30 year old machine that doesn't have a web browser available?! Well, sure, tough luck, then you need to do it the old school way and browse the sources. You can always find a corner case of "what if...?", but I find that totally unconvincing. Making the 99.9% case harder (when you have a web browser and a toolchain installed, etc.) to make the 0.1% case (when you don't) easier is a bad tradeoff.
- Brian_K_White 2y ago
  I don't understand how you don't understand the order of magnitude difference in flexibility, utility, availability, etc between needing to run a specific executable vs merely opening a text file in any way. "you always have the exe" is just not even remotely a valid argument.
  - nindalf 2y ago
    I don’t understand how you don’t understand that that’s always an option. Rust source files are written in plaintext too. There are a few people in this thread, including you, who claim that they vastly prefer the output of documentation to be plain text in a single file rather than linked HTML files OR reading the source in multiple plaintext files. That’s a preference, so y’all can’t be wrong. But consider that if this preference was even slightly popular, cargo doc would probably get a —-text option that output everything in a single text file. The fact that it doesn’t have it tells me that this preference is very niche.
pornel 2y ago
Yes, it works with GitHub, GitLab, Bitbucket, and everything else. It's built into the compiler toolchain. It works with every syntax that you can compile, because it uses the compiler itself to extract the documentation. Yes, it works on Windows too. Rust supports Windows as a first-class platform. It works with dependencies too (the docs even link across packages). The fragmentation of C tooling and unreliability/complexity of integrating with C builds is not a universal problem. Rust's built-in documentation generator creates HTML, so anything with a browser can show it. It also has JSON format for 3rd party tooling. The same language syntax for the documentation is understood by Rust's LSP server, so vim, emacs, and other editors with LSP plugins can show the documentation inline too. I've been using this for years, and it works great. I don't miss maintaining C headers at all. I write function definitions once, document them in the same place where the code is, and get high fidelity always up-to-date API docs automatically.

by jmb99 2y ago

Dylan16807 2y ago

> I shouldn’t have to install a toolchain (let alone rely on a web browser) to read API documentation. Why are you reading a library API for a language you're not coding in? I'm sure you can come up with some situation, but that situation should NOT be what we optimize for. And web browsers are fine. > is it is easy as opening a .h in notepad and reading it If you include the actual ease of reading, yeah it should be.

nindalf 2y ago

> I could go on Please do. It just sounds like you’re nitpicking. If you can open a browser, open docs.rs. The GitHub repo usually contains a link to docs.rs because that’s how people prefer to read the documentation. If you prefer working without the internet that’s fine too. Use cargo doc, which opens the rendered doc page in a local web browser. If you prefer being in a text editor exclusively, no problem! Grep for `pub` and read the doc comments right above (these start with ///). No toolchain necessary. Look, most normal people don’t have some intense phobia of web browsers, so they’d prefer docs.rs. For the people who prefer text editor, it’s still a great experience - git clone and look for the doc comments. The point is, the existence of docs.rs only encourages Rust library developers to write more and better documentation, which everyone, including text editor exclusive people benefit from. That’s why your comment sounds so strange.

devvvvvvv 2y ago
[flagged]
- hooli_gan 2y ago
  Most normal people don't read documentation of programming libraries.
- estebank 2y ago
  Most normal people don't comment on hackernews, yet here we are.

kouteiheika 2y ago

> So it’s built into GitLab and GitHub? BitBucket? No. It's built into the toolchain which every Rust developer has installed. > How easy is it to use on windows (i.e. is it is easy as opening a .h in notepad and reading it)? A easy as on Linux or macOS from my experience. > How easy is it to use from a command line environment with vim or emacs bindings? Not sure I understand the question; use how exactly? You either have a binding which runs `cargo doc` and opens the docs for you, or you use an LSP server and a plugin for your editor in which case the docs are integrated into your editor. > I shouldn’t have to install a toolchain (let alone rely on a web browser) to read API documentation. If you want you can just read the source code, just as you do for any other language, because the docs are right there in the sources. For publicly available libraries you can also type in `https://docs.rs/$name_of_library https://docs.rs/$name_of_library` in your web browser to open the docs. Any library available through crates.io (so 99.9% of what people use) have docs available there, so even if you don't have the toolchain installed/are on your phone you can still browse through the docs. I know what you're going to say - what if you don't have the toolchain installed and the library is not public? Or, worse, you're using a 30 year old machine that doesn't have a web browser available?! Well, sure, tough luck, then you need to do it the old school way and browse the sources. You can always find a corner case of "what if...?", but I find that totally unconvincing. Making the 99.9% case harder (when you have a web browser and a toolchain installed, etc.) to make the 0.1% case (when you don't) easier is a bad tradeoff.

Brian_K_White 2y ago
I don't understand how you don't understand the order of magnitude difference in flexibility, utility, availability, etc between needing to run a specific executable vs merely opening a text file in any way. "you always have the exe" is just not even remotely a valid argument.
- nindalf 2y ago
  I don’t understand how you don’t understand that that’s always an option. Rust source files are written in plaintext too. There are a few people in this thread, including you, who claim that they vastly prefer the output of documentation to be plain text in a single file rather than linked HTML files OR reading the source in multiple plaintext files. That’s a preference, so y’all can’t be wrong. But consider that if this preference was even slightly popular, cargo doc would probably get a —-text option that output everything in a single text file. The fact that it doesn’t have it tells me that this preference is very niche.

pornel 2y ago

Yes, it works with GitHub, GitLab, Bitbucket, and everything else. It's built into the compiler toolchain. It works with every syntax that you can compile, because it uses the compiler itself to extract the documentation. Yes, it works on Windows too. Rust supports Windows as a first-class platform. It works with dependencies too (the docs even link across packages). The fragmentation of C tooling and unreliability/complexity of integrating with C builds is not a universal problem. Rust's built-in documentation generator creates HTML, so anything with a browser can show it. It also has JSON format for 3rd party tooling. The same language syntax for the documentation is understood by Rust's LSP server, so vim, emacs, and other editors with LSP plugins can show the documentation inline too. I've been using this for years, and it works great. I don't miss maintaining C headers at all. I write function definitions once, document them in the same place where the code is, and get high fidelity always up-to-date API docs automatically.