Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Rust 1.48

blog.rust-lang.org

Post reply on HN
Print view View original

31–40 of 119 posts

Re: Rust 1.48

#31

Post by Rusky »

mike-cardwell wrote: post #29
bluejekyll wrote: post #2

One 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…

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

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

Re: Rust 1.48

#32

Post by Rusky »

tasn wrote: post #15
bluejekyll wrote: post #2

One 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…

I 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…

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

Re: Rust 1.48

#33

Post by Buttons840 »

bluejekyll wrote: post #2

One 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…

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

Re: Rust 1.48

#34

Post by steveklabnik »

Rusky wrote: post #32
tasn wrote: post #15

Earlier quoted context omitted.

I 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…

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

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

Re: Rust 1.48

#35

Post by sitkack »

masklinn wrote: post #20
palerdot wrote: post #12

Earlier quoted context omitted.

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

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

I had to suffer with coworkers that would write doctests, bad docs and bad tests together at last!

The solution here is to write real tests and hyperlink them in a marked up form to the functions they actually test. Coding inside of a doc string is an epic troll.

This is a warning to anyone getting seduced by doctests, stay away! They invert the problem, when one should just write tests, it is a problem with the documentation and code discovery tools that makes this seem like a good idea.

Re: Rust 1.48

#36

Post by simias »

mark4 wrote: post #17
jph wrote: post #3

Congratulations! The highlight for me is stable conversion from Vec to array: let my_arr: [u32; 3] = my_vec.try_into().expect("msg");

Newbie question. Why is this useful? Wouldn't slices be enough to fulfill the use-cases this would see?

steveklabnik is (of course) correct, but you also have to consider the performance cost of a dynamicaly sized slice versus a statically sized array.

A situation I've encountered several times already is implementing statically sized FIFOs. At the moment in Rust I can't implement a type "FIFO of depth N" where is a generic, static parameter. My only choices are implementing "FIFO of depth n" where n is provided dynamically at runtime (and implemented internally using something like a VecDeque) or a completely fixed depth FIFO type that I need to duplicate for every depth (FIFO32, FIFO16, FIFO10 etc...).

If you require very high performance a dynamically checked FIFO can incur a fairly large overhead when a well optimized static FIFO can implement most operations in a couple of opcodes at most.

Re: Rust 1.48

#37

Post by est31 »

Buttons840 wrote: post #33
bluejekyll wrote: post #2

One 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…

Is 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 lo…

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

Re: Rust 1.48

#38

Post by steveklabnik »

est31 wrote: post #37
Buttons840 wrote: post #33

Earlier quoted context omitted.

Is 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 lo…

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

You need a -Z unstable-options in there too, but this does not work for me with the latest nightly.

Re: Rust 1.48

#39

Post by steveklabnik »

sitkack wrote: post #35
masklinn wrote: post #20

Earlier quoted context omitted.

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

I had to suffer with coworkers that would write doctests, bad docs and bad tests together at last! The solution here is to write real tests and hyperlink them in a marked up form to the functions they actually test. Coding inside of a doc string is an epic troll. This is a warning to anyone getting seduced by doctests, stay away! They invert the problem, when one should just write tests, it is a problem with the docu…

What is the distinction between a "real" test and a doc test that you're making? At least in Rust, they are the same thing.

Re: Rust 1.48

#40

Post by est31 »

steveklabnik wrote: post #22
masklinn wrote: post #20

Earlier quoted context omitted.

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

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

Rust 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.
Post reply on HN