[kouteiheika]

> 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` 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]

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.

[kouteiheika]

> "you always have the exe" is just not even remotely a valid argument.

Why? Can you explain it to me?

I'm a Rust developer. I use my work station every day for 8 hours to write code. I also use `cargo doc` (the tool for which "I always have the exe") every day to look up API docs, and in total this saves me a ton of time every month (probably multiple hours at least, if I'm working with unfamiliar libraries), and I save even more time because I don't have to maintain separate header files (because Rust doesn't have them).

Can you explain the superior flexibility and utility of "merely opening a text file" over this approach, and how that would make me (and my colleagues at work) more productive and save me time?

I'm not being sarcastic here; genuinely, please convince me that I'm wrong. I've been a C developer for over 20 years and I did it the "opening a text file" way and never want to go back, but maybe you're seeing something here that I never saw myself, in which case please enlighten me.

[Dylan16807]

It's less available in rare situations.

It's not less flexible once you already took availability into account.

It has more utility, that's the entire point.

[nindalf]

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.