Hacker News Reader

Comment by exacube | Hacker News Reader

I'm happy things are moving along, but I would still like to see the documentation be more polished. I still don't know how to write a task queue (ie queue of closures) that executors can concurrently read and run from.

I don't feel like the docs empower me enough to write multi threaded code comfortably without the borrow checker spitting at me. Is it just me, or does anyone else feel this way?

View on HN

When you start documenting a language from scratch, you have to start at the beginning. A language is a huge project as well. The current book is about ~250 pages when rendered as a PDF. I've finally gotten to the point where the basics of almost everything have been documented, and am starting to move on to more intermediate style things.

In addition, we've only had a stable Rust for six weeks: there just hasn't been enough time to write more advanced things. Nobody wants to invest in stuff while things are still changing. As an example of this, I know there's an O'Reilly book coming out in the fall which covers advanced topics exclusively.

A basic task pool isn't too many lines of code: https://github.com/rust-lang/threadpool/blob/master/src/lib.... Hopefully that can help for that case, though obviously, this isn't just a comment about threadpools :)

I love the rust docs, but I do agree that the intermediate/advanced stuff is missing. I won't feel like I truly understand until I can implement a bunch of different datastructures, and it turns out that that is exactly the kind of code that throws up lifetime issues that as a beginning rust programmer I'm not really prepared to deal with.

I'd love a 'learn to write rust with datastructures' style intermediate tutorial.

You may also be interested in this post[1] by nrc for a couple of strategies for implementing graphs. And this companion[2] by Niko Matsakis.

[1] https://github.com/nrc/r4cppp/blob/master/graphs/README.md [2] http://smallcultfollowing.com/babysteps/blog/2015/04/06/mode...

You might be interested in https://internals.rust-lang.org/t/the-unsafe-rust-programmin...

I don't want to make you rewrite this if you've already answered this elsewhere, but...

Could you provide some pointers about how to begin with contributing to the Rust documentation? What are the areas that need the most help or have received the most complaints/confused reactions? I actually like writing docs but I'm not sure where I'd begin. (And of course not super confident in my understanding of Rust in the first place since I'm still learning it myself. But I know a lot more than someone looking at it for the first time.)

I'd love to have some contributions! One easy way to contribute is to find something that doesn't currently have any examples, and add some. http://doc.rust-lang.org/stable/book/documentation.html is a basic guide to writing docs, and I'm quite happy to workshop a PR with some basics into something more.

Currently, the areas that need most help fall into two categories: intermediate/advanced docs, and API documentation. The latter is an easier place to get started, I'd imagine. Hence my suggestion of examples.

We also have the A-docs tag: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Ais... Some of these are actually pretty easy, I tend to let the pile up and then knock out 10+ in a day if nobody else gets them first.

I can get more specific than that if you'd like, but I think that's a pretty decent high-level overview.

One thing you can do if you'd like to help with docs is to flesh out Rust By Example: https://github.com/rust-lang/rust-by-example . It began as a community project but was then adopted by the core developers at the behest of the community, but it's seen much less love than the official docs. If you're interested you'd be largely free to make it your own. :)

Thank you, you're doing a great job!!

Thank _you_ :)

I have another exciting documentation-related announcement in the pipeline, but I'm currently waiting on some lawyers...

You need a non-blocking lawyer queue.

i.e. a cliff?

Better call Saul!

I really love that you can (have?) put tests in the same file as the threadpool implementation. I think I will start doing this myself...

Rust convention is to put unit tests in the same file. I like it too :)

Also, doc comments run as tests too, so https://github.com/rust-lang/threadpool/blob/master/src/lib.... will actually get executed as a test.

Reply on news.ycombinator.com