Hacker News Reader

Comment by zozbot234 | Hacker News Reader

QuickBASIC works the same way. Rust doesn't really build its help documentation for "built-in" access in the programming environment (everything is web-based, even "local" docs launch in a web browser) but examples are a first-class feature; they're reused as test cases.

View on HN

Even though the Rust docs aren't built for this purpose first, in IntelliJ or CLion I can still press Ctrl + Q on a method and see the full method documentation with examples. I think what IntelliJ does is simply parse the doc comment for that method and then render the markdown contained in it in the little popup. The standard docs are built from those comments as well.

> Rust [...] everything is web-based

Correction: Rust's help and documentation is HTML-based, and getting a local, automatically updated copy is trivial.

> even "local" docs launch in a web browser

Uh, so what? Can you name a better format for programming language documentation that's also ubiquitously supported?

> Can you name a better format for programming language documentation that's also ubiquitously supported?

Info format. It's supported by Emacs, and Emacs is the most ubiquitous of IDE's.

> Emacs is the most ubiquitous of IDE's.

Sorry, have you been in a coma for 30 years?

Your question is rhetorical here, right?

> Info format.

I said "ubiquitously supported". There are several orders of magnitude difference between info format support and HTML support.

> Emacs is the most ubiquitous of IDE's

That's laughably wrong.

Well, it may be on everyone's machine (just type 'which emacs') but that hardly makes it the most commonly used IDE, which I think is what's hard to stomach.

Well, JavaDoc is a mix of HTML and custom tag language based, whereas Kotlin moved to Markdown + some similar tags. Because HTML is a pain in the rear to write compared to Markdown and can't express everything you want concisely.

Maybe you mean Rust's documentation is rendered to HTML. In which case, sure, but so what? Good docs can be rendered to non-HTML formats too, typically for IDEs to display quickly without needing to load a full browser.

With Go, the ability to instantly read docs for anything (even just pulling docs for a single function) in terminal is extremely helpful and far superior to a HTML-only approach. "go doc net/http.Client" pulls up the docs for the http client type.

It's one of the features I miss most as I code Rust, and the lack is very detrimental to the coding experience, as pulling up a browser is a massive context switch.

it's a mere scripting language, but I love the similar way powershell does this also, get-help [some-command] -examples

Talking about that, rust html docs gobs a whopping 400MB (2/3 of the install size IIRC). When compressed they're 22MB.

Rust and cargo are quite wasteful of disk space anyway, they should fix that first. 400MB is a drop in the bucket.

Not long ago, there was support on Firefox to directly open HTML pages within compressed files (through the jar: protocol). If that still existed, it would be an option to distribute the rust HTML docs within a compressed .jar file, and let the browser read directly from it.

yeah that's a pity

albeit there's still zcat

Reply on news.ycombinator.com