[salgernon]

I’m with parent - what if you don’t have the tool? What if there’s a syntax error in some implementation or dependency such that the tool chokes early?

Human readable headers are accessible out of context if the implementation. They also help provide a clear abstraction - this is the contract. This is what I support as of this version. (And hopefully with appropriate annotations across versions)

[kouteiheika]

> I’m with parent - what if you don’t have the tool?

The "what if you don't have the tool" situation never happens in case of Rust. If you have the compiler you have the tool, because it's always included with the compiler. This isn't some third party tool that you install manually; it's arguably part of the language.

> What if there’s a syntax error in some implementation or dependency such that the tool chokes early?

In C I can see how this can happen with its mess of a build systems; in Rust this doesn't happen (in my 10+ years of Rust I've never seen it), because people don't publish libraries with syntax errors (duh!).

[TheNewAndy]

"Never" is a big call.

In this specific case, your tool requires a web browser (though I'm assuming that there is a non-web browser form of what is being sold here). Maybe you are in a situation where you only have terminal access to the machine.

Maybe you are on your phone just browsing github looking for a library to use

I'm sure people can continue to imagine more examples. It is entirely possible that we have different experiences of projects and teams.

[nindalf]

> I’m sure people can continue to imagine more examples

Hopefully they’ll imagine more compelling examples.

If the hypothetical person’s phone is capable of browsing GitHub, I don’t see why they can’t also browse docs.rs. It renders well on small screens. That’s not a hypothetical, I’ve actually read the docs for libraries on my phone.

[jmb99]

> 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.

[nindalf]

> 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.

[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.

[pornel]

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.

[Dylan16807]

> 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.

[gary_0]

The "what if you don't have the software" argument doesn't hold water for me. What if you don't have git? What if you don't have a text editor? What if you don't have a filesystem?

Most programming language communities are okay with expecting a certain amount of (modern) tooling, and C can't rely on legacy to remain relevant forever...