Review of the state of the FAQ

[alilleybrinker]

Maintenance of the FAQ has fallen by the wayside, and this is largely my fault, and something I'd like to fix. To get that started, I've just gone through the FAQ and noted problems which ought to be addressed. This can act a tracking issue for getting these issues fixed, which I will start to work on.

Without further ado, here's the list:

“What is this project’s goal”

• Is this still a good goal statement?
• Is the FAQ the right place to have this answer?

“Is this project controlled by Mozilla?“

• Update the number of unique contributors.
• Should the yearly review cycle be in here?
• Should the yearly review cycle be it’s own question & answer?

“In which projects is Mozilla using Rust?“

• Update to include info about Rust use in Firefox.

“What examples are there of large Rust projects?“

• See if there are larger projects which could warrant adding.

“How can I try Rust easily?”

• “playpen” -> “playground”
• Maybe just direct people to the book in general, instead of specifically the guessing game.

“How do I get help with Rust issues?”

• Remove /r/rust, because it’s not an official channel.

“Why has Rust changed so much over time?”

• Link to Rust’s specific stability policy.

“How fast is Rust?“

• Include links to more benchmarks and comparisons?

“Why curly braces? Why can’t Rust’s syntax be like Haskell’s or Python’s?”

• Remove reference to the complexity of the parser in the compiler.

“How can I convert between numeric types?“

• This should be more thorough in explaining all the available conversions between numeric types, and what limitations they face.
• Maybe include mention of TryFrom?

“How can I convert a String or Vec<T> to a slice (&str and &[T])?“

• Make the first paragraph clearer.
• Honestly, this relies on understanding Deref coercions, and that dependency should be clearer.

"How do you deal with a ‘use of moved value’ error?“

• The bit on refactoring is really unsatisfactory. There should be a clearer guide to how you “untangle the ownership” in situations like this.

“How do I return a closure from a function?“

• I am not familiar with the interaction, but does impl Trait change any of the answer here, with regards to the use of Box?

“Why lifetimes?“

• A better answer is to say that lifetimes exist in languages like C and C++, but they’re for the programmer to track. Rust’s usefulness is that they are explicitly tracked and use to verify safety in Rust.

“What is ‘monomorphisation’?“

• We’re using the UK English spelling here. Do we want to be? Do we have a policy for this?

“What are higher-kinder types, why would I want them, and why doesn’t Rust have them?”

• This answer is unsatisfactory. I know @withoutboats has issues with it, and of course if Associated Type Constructors lands, there will be things to say about all of that here. It needs a major rewrite.

“How do I read a file into a String?“

• Should there be answers for other basic I/O operations?

“How do I do asynchronous input / output in Rust?“

• A lot has happened in this space since this answer was written. Probably want to talk about Mio, Futures, and Tokio.
• Also, Rayon is awesome and should get some mention in here.

“What the deal with unwrap() everywhere?“

• The existence of the ? should probably be mentioned.

“How do I get an error when I try to run example code that uses the try! macro?”

• The use of try! (and of course ? by extension) inside of main has been accepted as an RFC. This should be mentioned.

Concurrency

• This whole section is woefully incomplete. Should probably go to the community to solicit questions on this topic.

Macros

• Same as concurrency. We need a much more complete set of questions and answers here.

Debugging and Tooling

• None of this mentions the Rust Language Server, or the Intellij Rust plugin, which is now official and supported.

Low-Level

• This whole section could be a lot more complete.
• Probably want to include a link to the unsafe code guidelines effort.
• Honestly, a whole book could be written on how low-level programming is done in Rust. Hopefully someone writes it.

Cross-Platform

• Nothing here on cross-platform GUIs, which are often asked about. This should change.

Modules and Crates

• Given the possibility of impending changes in this area, I anticipate needing to update / rewrite these questions and answers.

Libraries

• Should this section even be here?

Design Patterns

• The OO answers should be fleshed out. I know @wycats has had some great things to offer on this front.

Other Languages

• There are always more comparisons to make. Let’s solicit more questions!

Documentation

• Wow, this doesn’t even mention the Docs Team! Let’s fix that!

EDIT:

There are some existing issues that should also be addressed:

• No collection of community libraries #271
• Misleading HKT answer in FAQ #401
• Clarify Rust's relationship to OO in the FAQ #476