12 ms·
Rust 1.48
- bluejekyll 6y agoOne of the things that made me so excited about Rust when I first used it was the capabilities of the Rustdoc system. The built in examples that are also unit tests, the ease of just using markdown... and now the linking is even simpler. It’s one of my favorite things about the language, and I think is why so many crates have such good documentation, because it’s easy to do. (and it’s tested and validated so you know it’s right!)
- 0-_-0 6y agoNot directly related, but when I was learning programming back in highschool (before the Internet) what made it easy was the built in help in Turbo Pascal. You could press F1 over any function or keyword and you were given a detailed description and example of usage. Learning C later using the K&R book and Google was a huge downgrade. Even today I think that language help built into the IDE should be a basic functionality.
- LandR 6y agoThis is done quite nicely with clojuredocs being intergrated into Cursive / Intellij. I hover over a Clojure function in INtelliJ and I get a pop up of the clojuredocs with description and example usages for that function. It's great and I don't know why more IDE's don't do this. Why isn't VS linked to the MSDN for C# / .NET ? SO I can get the information for that function / class / library etc straight in my IDE!
- trevyn 6y agoBringing it back, this works great with Rust and VSCode and rust-analyzer: Any function in any crate shows its doc comment complete with markdown formatting when you hover over it.
- CryZe 6y agoAnd you can assign a hotkey to open the docs in the browser for the symbol under the cursor.
- hobby-coder-guy 6y agoIntegrated
- identity0 6y agoIn vim if you press K it will bring up the man page for the word under your cursor. It was very useful when learning C, considering that most libc functions have helpful man pages.
- imron 6y agoNote for people trying this at home, vim is case sensitive. I still regularly use this feature to look up libc and other things. You can also type 2K to go to ‘man 2’, or 3K to go to ‘man 3’ etc.
- JNRowe 6y agoAnd for the sake of completeness, it is not just for man pages either. vim simply calls 'keywordprg' with the word under the cursor, so you can use whatever you feel like. Open a browser tab on your favourite documentation, display an ERD, pop open a picture of a kitten, … Many filetype plugins come with pre-configured 'keywordprg' settings. Including some non-programming filetypes like git which will execute `git show <word>`, which is great if you're the type of person who often references commits in other commit messages.
- imron 6y agoTIL. This will make this feature even more useful than I already found it.
- Boulth6 6y agoI've seen that with Delphi. The unique factor was that the examples were not a basic call of the function but an actual real world practical sample that usually solved the problem one was looking for.
- geoelectric 6y agoI was a Delphi programmer for a few years, professionally, when it first came out in the 90s. I worked with their developer products (and for Borland directly on Delphi/Kylix/C++Builder, eventually) until the mid-2000s. I've never seen the match of Borland's docs, before or since, particularly as integrated with the IDE's coding features. There are a number of programming languages and APIs with excellent documentation, but theirs were above and beyond.
- pkphilip 6y agoThe Delphi IDE help was good but the printed Delphi manuals were just outstanding. I have fond memories of learning much through those manuals.
- pjmlp 6y agoI have them in print still, including the MS-DOS ones (TP), if you don't have them any longer, they are available at bitsavers.
- geoelectric 6y agoI had forgotten the “brick” you used to buy with a few CDs (or floppies) and a whole stack of books. Things sure were heavy before the internet got fast.
- rudedogg 6y agoI always loved this site: http://www.delphibasics.co.uk/RTL.asp?Name=ansicomparestr http://www.delphibasics.co.uk/RTL.asp?Name=ansicomparestr
- erk__ 6y agoThis is one of the things I love about Mathematica, it has a lot of documentation about every keyword and function that you can open with F1.
- gtrhtrhtrhtr 6y agoI've seen this with bpython
- deleted 6y ago[deleted]
- heavenlyblue 6y agoYou could do the same with C in Visual Studio for at least 15 years now
- 0-_-0 6y agoThat requires an internet connection and opens a page in your browser.
- pjmlp 6y agoNope, because one would install the MSDN documentation locally from the bundled CDs and use Windows help infrastructure. The Web version came much later.
- 0-_-0 6y agoWhich means that currently it requires an internet connection and opens a page in your browser.
- pjmlp 6y agoNo it doesn't. https://docs.microsoft.com/en-us/visualstudio/help-viewer/overview?view=vs-2019 https://docs.microsoft.com/en-us/visualstudio/help-viewer/ov...
- 0-_-0 6y agoHave you actually tried that? I just installed it and it's just a buch of help files that link to the web. F1 continues to work the same way, bringing up websites, often useless ones like this one for a for loop: https://docs.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.operations.loopkind?f1url=%3FappId%3DDev16IDEF1%26l%3DEN-US%26k%3Dk(FUNCTIONAL%252Fstd%253A%253Afunction%253A%253Afunction);k(std%253A%253Afunction%253A%253Afunction);k(for);k(DevLang-C%252B%252B);k(TargetOS-Windows)%26rd%3Dtrue&view=roslyn-dotnet https://docs.microsoft.com/en-us/dotnet/api/microsoft.codean...
- palerdot 6y agoElixir also has this feature called doctests[0]. That said, rust documentation is also really good. [0] - https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html#doctests https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...
- hangtwenty 6y agoI am so glad to learn about these features in Rust and Elixir. I'm coming from Python originally, so I always want them! https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html https://docs.pytest.org/en/stable/doctest.html https://docs.pytest.org/en/stable/doctest.html
- mcintyre1994 6y agoI had no idea that Python had a library for this, nice! Skimming that doc, it's especially impressive how well it looks to handle exception tracebacks.
- masklinn 6y agoI mean doctests are not exactly new. The `doctest` module was added to Python in 2.1, back in 2001. And even that is largely just a weak shade of semi-literate programming, to say nothing of actual literate programming.
- steveklabnik 6y agoThis is one of the things I really love about Rust, and also one of the things that's most challenging for its adoption. Not a ton of stuff in Rust is new, but it does present a new mix of old things, and often, those things are new to many people, even if they're actually old.
- est31 6y agoRust took out the things considered best practice and provided them to users by default, or checked for them by default. This includes simple things as explicit names for types like u8 instead of char (as you are going to assume the size of char anyway, let's be honest... most code won't work on 16 bit char platforms). But it also includes stuff like unifying naming conventions, or providing a good package manager. C++ has multiple package managers, as does js. But rust had a great one from the start and for now there doesnt seem to be the need for people to use alternatives, because nobody had to come up with them. So no balkanization of standards and the costs for users that this entails. Maybe with age this will change, but for now Rust is doing quite well.
- tasn 6y agoI also like Rustdoc, using markdown and the new linking improvements. It's much better than learning yet another DSL. However, there's one thing I find annoying, and that's the lack of a structure for parameters. Following the `# Arguments:` convention is redundant (I get it's petty, but I'm annoyed every time I write it), but more than that it's error-prone and limiting. Because arguments names are just a convention that's not strictly enforced, it's not automatically checking the naming is correct, and it limits the ability of tools like cbindgen and flapigen (love them both) to transform param specific docs.
- Rusky 6y agoI've seen the argument (not sure if this factored into rustdoc's design or if it's just someone's opinion) that structured per-parameter docs tend toward useless boilerplate, e.g. "foo: a foo object," while a holistic description of the function itself is easier to make useful.
- steveklabnik 6y agoI don't know if it really factored into rustdoc's design since it was already built when I came to Rust, but when I was part of the team responsible for rustdoc, I did object to suggestions we do this on that basis. As well as, extending the underlying language (that is, markdown) has to be done really carefully, and so being conservative with how it's done matters. This was a huge part of figuring out the design of intra-doc links in the first place. (All of this great work is being done by others, and I don't know what their opinion on it really is, so my opinion being -1 doesn't really matter these days.)
- vbarrielle 6y agoAgreed, I find per-parameter docs useful in dynamic languages such as python, or to a lesser extent useful when the type system is weaker (in C), but in Rust I seldom find them useful. This can be useful to express constraints not present in the type system, for instance `fn matmul(a: Matrix<f64>, b: Matrix<f64>) -> Matrix<f64>` will benefit from a documentation describing the constraints and guarantees on the number of rows and cols of each matrix, since this cannot be expressed in the type system (yet).
- stabbles 6y agoYeah, this is great. Julia has it since a couple years in the Documenter package. Plus basic Markdown rendering in the REPL when you hit `?func`. Markdown + extension to understand language specific cross-references is powerful! [1] [1] https://juliadocs.github.io/Documenter.jl/stable/man/guide/#Cross-Referencing https://juliadocs.github.io/Documenter.jl/stable/man/guide/#...
- mhh__ 6y agoThis is how ddoc works in D, too. Markdown arrived recently as well
- mike-cardwell 6y agoI've always found crate documentation to be the worse thing about Rust. Because it auto-generates some documentation, people just assume that's good enough, and you end up with tonnes of crates that seemingly only have a list of functions and structs and what arguments they take, but very little information about how you're supposed to plug everything together.
- lights0123 6y ago> people just assume that's good enough really? I've found that in general the same number of people bother to go deep into explaining compared to e.g. JS, and always having rustdoc for the people that don't is far better than reading the source or TypeScript definitions.
- Rusky 6y agoBoth are true, in my experience. Lots of good documentation for some crates, while others (usually with fewer maintainers or less intention of reuse) just have the autogenerated index.
- throwaway894345 6y agoAt least you get that. In the (untyped) Python ecosystem, you're lucky to get "this parameter is a file-like object" even though "file-like" doesn't tell you if it just supports read() and write() or also seek() or close() or truncate(). You have to dig into the source code, which likely just passes the parameter into another function which passes it into another and then across a library boundary and so on. And again, that's the best-case scenario. Just having correct type information is 80% of the battle IMHO.
- skrtskrt 6y agoGo is the same. Everyone, including the stdlib maintainers seem to think a few lines of comments per method is the same as documentation on how to use the package, best practices, pitfalls, etc.
- x87678r 6y agoJava is the same as well
- Buttons840 6y agoIs it possible to link your local core and library docs yet? I have my dependencies documented locally, I have the standard library documented locally, both of these work well with the ability to do searches just like the online docs. The problem is they're separate. The local docs for one of my crates cannot link to my local standard library docs; instead, I have to jump around different browser tabs and manually look things up. There used to be some hacks that could work around this, but those hacks stopped working.
- est31 6y agoInteresting question. Does RUSTDOCFLAGS="--extern-html-root-url std=file:///path/to/std/docs" cargo doc work? You can repeat it for std, core, alloc, proc-macro, etc.
- steveklabnik 6y agoYou need a -Z unstable-options in there too, but this does not work for me with the latest nightly.
- est31 6y agoHmm apparently there is a cargo feature for it now: https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/unstable.md#rustdoc-map https://github.com/rust-lang/cargo/blob/master/src/doc/src/r... So something like this in .cargo/config: [doc.extern-map] std = "local" And then cargo +nightly doc -Zrustdoc-map.
- steveklabnik 6y agoVery cool!
- heavyset_go 6y agoThis is a great feature, but it is also present in many languages. For example, doctest[1] is included with Python, and allows for tests in docstrings. [1] https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html
- kevincox 6y agoI also love that it is consistent between projects. The fact that I can just go to https://docs.rs/chrono https://docs.rs/chrono for any public project and have a consistent interface for reading and navigating is huge. Of course this is somewhat fickle and makes competing documentation generations harder to get started but as a user when rustdoc is really good it is a nice benifit.
- jph 6y agoCongratulations! The highlight for me is stable conversion from Vec to array: let my_arr: [u32; 3] = my_vec.try_into().expect("msg");
- simias 6y agoIndeed, I can't wait for const generics to become available outside of std, I've been bumping into that limitation since pre-rust-1.0 days, it'll be amazing to finally be able to rewrite all that hacky code correctly.
- nicoburns 6y agomin_const_generics is targeted for Rust 1.50 :)
- matt_kantor 6y agoFor anyone who wants to learn more: https://github.com/rust-lang/rust/pull/79135 https://github.com/rust-lang/rust/pull/79135
- wyldfire 6y agoHmm. Could you do this kind of code for a static allocation at compile-time too?
- efnx 6y agoI don’t think so - you can only use static functions to declare static variables. But you could do it with a macro. It’s debatable whether that would be readable and predictable, though.
- steveklabnik 6y agoI believe https://github.com/rust-lang/const-eval/issues/20 https://github.com/rust-lang/const-eval/issues/20 is the entry point into this kind of thing. As you can see, there's a lot of discussion. If it ever lands it'll be farther out.
- ibraheemdev 6y ago[`Bar`](crate::bar::Bar) vs. [`Bar`](../bar/struct.Bar.html). Thank you!
- DC-3 6y agoOn the one hand it's not hugely thrilling for the headline features of a new release to be improvements to doc tooling and a stabilized trait impl but on the other hand it's good to see the language settling down and maturing.
- pas 6y agoThere are big changes under the hood. And those regularly make HN front page. Like the recent Cranelift codegen backend to help with the coding-compiling cycle time. Similarly there's regularly ~350 PRs merged each week into rust. (The libification and chalkification is ongoing, which is the next-gen solver for the type/trait system, plus at the same time some refactor of the compiler to make it more like a usable library, so rust-analyzer can use it to provide more immediate/incremental feedback during development.)
- est31 6y agoThe next two releases will be bigger. The 1.49 release will have a new tier 1 target (aarch64-unknown-linux-gnu) as well as apple silicon as a tier 2 target. The 1.50 release will have min const generics as well as stable backtraces. As the releases are every 6 weeks, an individual one might seem small. But over time they add up. Note though that I do consider the rustdoc improvements to be major. Previously I wasn't bothering with directly linking to referenced items because you had to figure out html names. Now it's very easy and I plan to write more links.
- scottlamb 6y agoI'm indeed excited about those! There have been releases where ARM (maybe I was using armv7 rather than aarch64 then, but I'm on aarch64 now) was totally broken, and now I know that won't happen on 1.49 or beyond. Min const generics...I'm not sure I'll find much use for it until const_evaluatable_checked happens, but I'm glad to see progress. Stable backtraces will mean I can stop using the deprecated failure crate without giving up my quality diagnostics.
- xiphias2 6y agoThese may be major changes for devs, but for beginners who want to learn Rust without it changing under them all the time, these are not major changes anymore. Which is a great thing!
- juancampa 6y agoI wish they have used a different word than `const` for "not necessarily constant but it can be called at compile time". This is bound to confuse newcomers. Note this is unrelated to this release but I just realized how confusing it could be.
- steveklabnik 6y agoThe downside there would be explaining how that new word maps to Rust's concept of const, unless you'd change all of that too.
- tempodox 6y agoLike `comptime` in Zig, I find that quite self-explanatory.
- steveklabnik 6y agoconst fns are not inherently evaluated at compile time, so that would be a misnomer.
- kevincox 6y agoMaybe `pure`. Then it is fairly straightforward to explain that the computation of `const` values must be `pure`.
- steveklabnik 6y agoFun fact: Rust did use "pure" a very long time ago... https://news.ycombinator.com/item?id=24295941 https://news.ycombinator.com/item?id=24295941 It has its own challenges. Consider: const fn foo(x: &mut i32) { *x += 1; } would you consider this function pure? I don't think many would. Also, it may be pure given Rust's semantics, but it kinda goes against the intuitive, usual way people talk about purity, so that makes it hard. (This is not yet stable in Rust, but will be.)
- vallas 6y agoWhat are the things that need to be solved in next versions?
- kamilafsar 6y agoA few months ago I tried Rust but found that the tooling like auto completion and highlighting where still a bit alpha. IIRC I used VSCode with the most popular Rust plugin at the time. Did I miss something or is there some progress being made in that respect?
- laszlokorte 6y agonot sure which plugin you used but rust-analyzer is the way to go.
- steveklabnik 6y agorust-analyzer gets better and better every week.
- hobofan 6y agoSounds a bit strange. I'm using rust-analyzer in combination with TabNine (which both have integrations in every major editor), and it's among the best completion I've encountered across languages (though there are some limitations when it comes to proc-macros). Maybe it was still downloading some required binaries in the background when you were trying it out?
- trevyn 6y agoI’d love to see an open-source clone of TabNine.
- stusmall 6y agoAs others have said, I'd be curious what plug in you use. The state of things is pretty good. I'm using the IntelliJ Rust plugin and love it. It also provides pretty good inline annotation of inferred types which I find to be a big time saver.
- ZeroCool2u 6y agoCLion with the Rust plugin is pretty great.
- heavyset_go 6y ago
- deleted 6y ago[deleted]
- jiggawatts 6y agoJust in time for the Advent-of-Code 2020 challenge...