25 ms·

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

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 2y ago
> 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 2y ago
  "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 2y ago
    > 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 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]
gary_0 2y ago
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...

kouteiheika 2y ago

> 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 2y ago
"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 2y ago
  > 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 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]

gary_0 2y ago

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