Change:
Here's what I would like to be able to do: Visit In the search box, type any keyword, such as Get back comprehensive documentation about 's functionality, similar to the documentation for the primitive types (ex: ) For unused but reserved keywords, I would expect to see something along the lines of "This keyword has no current functionality but is reserved for Rust to possibly use in the future." Currently, all the details about pattern matching syntax is only documented in , as far as I can tell. In the new version of the book, . But if we remove documentation about, say, the precedence of and match guards, where will people go to learn about it? (). Furthermore, how is a new rustacean supposed to know that, say, and will return results but and will not? I'm going to research how the primitive types are documented, but wanted to file this for discussion purposes in the meantime.
It's hard for me to see how this fits into rustdoc, since rustdoc is primarily for documenting APIs (the primitives are a special case since they could be library types). This seems to call for a more integrated set of documentation that is searchable and cross-referable across sources. Which would be great.
It's indeed difficult to see how it could be integrated. Maybe an hybrid system: if some specific keywords are entered, we propose a link to the corresponding chapter of The Book?
But this info is being removed from the book, it should go somewhere else. On Jul 2, 2016 8:09 AM, "Guillaume Gomez" wrote:
Really? That complicates things a bit. We should then create a glossary for keywords.
And while I think about it: cc
So what should we do about it? I extended docs search quite a bit so at this point, I think we could create something similar that for primitives (ie, a tag and then you put your doc on it), and then we'd be mostly done (just a bit of design to conclude). Does that sound good to everyone? cc cc
We already have a way to tag docs onto a thing that doesn't have an item associated with it. The primitive pages all work by using a special attribute on an empty module, so we can easily cook up a similar for these. It would require making a new kind of page for them, but if we base it on the primitive pages (without all the method/trait implementations) it shouldn't be that bad. Writing all the docs, on the other hand, will require some footwork.
I'll work on adding the keyword pages first then. For the documentation, I may be not the best to write it.
I'm going to be honest, I not really a fan of this. Keywords aren't like anything else that rustdoc documents so it seems weird to shoehorn them in. Maybe what we really need is a combined search which covers the API, the books, the reference, the error index, etc... Then we could add a new book to cover all the keywords assuming they're not documented sufficiently elsewhere.
I guess this issue is kind of resolved? I checked the Rust docs and I see that you can already search for keywords (, and have documentation for example). I guess that means we can close this issue now? I did however found out that there are quite some keywords that do now have documentation yet. I went through the entire list of reserved keywords and these do currently not have any documentation. Keywords: break use dyn else in match mod move mut pub ref return self static super trait type unsafe while where Reserved for Future Use: abstract async become box do final macro override priv try typeof unsized virtual yield Personally I wonder if keywords like , and need some documentation since they are so basic to almost all programming languages. But I'll leave that up to you guys. I do however think that it would be better to create a new issue with a checklist and close this one, since it felt like the whole discussion here was about "how" we were going realize searching for keywords in the docs, instead of actually doing it.
There actually already is a tracking issue for this: . I don't know why both of these issues are open. FWIW I still don't think adding these docs to the docs was a good idea but I guess that ship has already sailed. Maybe we can turn them into a separate keyword book at some point instead though.
Ahh I guess we can close this one now then. I do think we at least make it more clear somehow that you can also search for keywords there. I mean currently it feels like you can only search for stdlib documentation there, but not for actual keywords.
I am also not really a fan but people seemed to like it.
It would also be nice to add the list of keywords to the , similar to the and sections. Because right now the only way to browse them is to open a documentation page and scroll down to the keywords list in the TOC.
it's there: , or did I misunderstood what you meant?
almost :) I meant a link in the TOC on the left (the one below the "See all std's items" section).
Oh I see! Can you open an issue for this please? (and cc me on it)
would be very happy for formal documentation about
Can you open a separate PR for it and ping on it please?
I checked the keywords in use that now have documentation (in the branch, it may not have reached stable yet): Done: as async await break const continue crate dyn else enum extern fn for if impl in let loop match move pub (very short, basically a link to the reference, when the others are often longer) struct true use while To do: - - - - - - unsafe (PR: ) -
The last PR for this is (unsafe keyword), after that it will be done !

Discussion:
#[doc(keyword = "unsafe")] // <del> /// Code or interfaces whose [memory safety] cannot be verified by the type system. </del> <ins> /// Code or interfaces whose [memory safety] cannot be verified by the type /// system. /// /// The `unsafe` keyword has two uses: to declare the existence of contracts the /// compiler can't check (`unsafe fn` and `unsafe trait`), and to declare that a /// programmer has checked that these contracts have been upheld (`unsafe {}` /// and `unsafe impl`, but also `unsafe fn` -- see below). They are not mutually /// exclusive, as can be seen in `unsafe fn`. /// /// # Unsafe abilities /// /// **No matter what, Safe Rust can't cause Undefined Behavior**. This is /// referred to as [soundness]: a well-typed program actually has the desired /// properties. The [Nomicon][nomicon-soundness] has a more detailed explanation /// on the subject. /// /// To ensure soundness, Safe Rust is restricted enough that it can be /// automatically checked. Sometimes, however, it is necessary to write code /// that is correct for reasons which are too clever for the compiler to /// understand. In those cases, you need to use Unsafe Rust. /// /// Here are the abilities Unsafe Rust has in addition to Safe Rust: /// /// - Dereference [raw pointers] /// - Implement `unsafe` [`trait`]s /// - Call `unsafe` functions /// - Mutate [`static`]s (including [`extern`]al ones) /// - Access fields of [`union`]s /// /// However, this extra power comes with extra responsibilities: it is now up to /// you to ensure soundness. The `unsafe` keyword helps by clearly marking the /// pieces of code that need to worry about this. /// /// ## The different meanings of `unsafe` /// /// Not all uses of `unsafe` are equivalent: some are here to mark the existence /// of a contract the programmer must check, others are to say "I have checked /// the contract, go ahead and do this". The following /// [discussion on Rust Internals] has more in-depth explanations about this but /// here is a summary of the main points: /// /// - `unsafe fn`: calling this function means abiding by a contract the /// compiler cannot enforce. /// - `unsafe trait`: implementing the [`trait`] means abiding by a /// contract the compiler cannot enforce. /// - `unsafe {}`: the contract necessary to call the operations inside the /// block has been checked by the programmer and is guaranteed to be respected. /// - `unsafe impl`: the contract necessary to implement the trait has been /// checked by the programmer and is guaranteed to be respected. /// /// `unsafe fn` also acts like an `unsafe {}` block /// around the code inside the function. This means it is not just a signal to /// the caller, but also promises that the preconditions for the operations /// inside the function are upheld. Mixing these two meanings can be confusing /// and [proposal]s exist to use `unsafe {}` blocks inside such functions when /// making `unsafe` operations. /// /// See the [Rustnomicon] and the [Reference] for more informations. </ins> /// <del> /// The documentation for this keyword is [not yet complete]. Pull requests welcome! </del> <ins> /// # Examples /// /// ## Marking elements as `unsafe` /// /// `unsafe` can be used on functions. Note that functions and statics declared /// in [`extern`] blocks are implicitly marked as `unsafe` (but not functions /// declared as `extern "something" fn ...`). Mutable statics are always unsafe, /// wherever they are declared. Methods can also be declared as `unsafe`: /// /// ```rust /// # #![allow(dead_code)] /// static mut FOO: &str = "hello"; /// /// unsafe fn unsafe_fn() {} /// /// extern "C" { ///     fn unsafe_extern_fn(); ///     static BAR: *mut u32; /// } /// /// trait SafeTraitWithUnsafeMethod { ///     unsafe fn unsafe_method(&self); /// } /// /// struct S; /// /// impl S { ///     unsafe fn unsafe_method_on_struct() {} /// } /// ``` /// /// Traits can also be declared as `unsafe`: /// /// ```rust /// unsafe trait UnsafeTrait {} /// ``` </ins> /// <ins> /// Since `unsafe fn` and `unsafe trait` indicate that there is a safety /// contract that the compiler cannot enforce, documenting it is important. The /// standard library has many examples of this, like the following which is an /// extract from [`Vec::set_len`]. The `# Safety` section explains the contract /// that must be fulfilled to safely call the function. /// /// ```rust,ignore (stub-to-show-doc-example) /// /// Forces the length of the vector to `new_len`. /// /// /// /// This is a low-level operation that maintains none of the normal /// /// invariants of the type. Normally changing the length of a vector /// /// is done using one of the safe operations instead, such as /// /// `truncate`, `resize`, `extend`, or `clear`. /// /// /// /// # Safety /// /// /// /// - `new_len` must be less than or equal to `capacity()`. /// /// - The elements at `old_len..new_len` must be initialized. /// pub unsafe fn set_len(&mut self, new_len: usize) /// ``` /// /// ## Using `unsafe {}` blocks and `impl`s /// /// Performing `unsafe` operations requires an `unsafe {}` block: /// /// ```rust /// # #![allow(dead_code)] /// /// Dereference the given pointer. /// /// /// /// # Safety /// /// /// /// `ptr` must be aligned and must not be dangling. /// unsafe fn deref_unchecked(ptr: *const i32) -> i32 { ///     *ptr /// } /// /// let a = 3; /// let b = &a as *const _; /// // SAFETY: `a` has not been dropped and references are always aligned, /// // so `b` is a valid address. /// unsafe { assert_eq!(*b, deref_unchecked(b)); }; /// ``` /// /// Traits marked as `unsafe` must be [`impl`]emented using `unsafe impl`. This /// makes a guarantee to other `unsafe` code that the implementation satisfies /// the trait's safety contract. The [Send] and [Sync] traits are examples of /// this behaviour in the standard library. /// /// ```rust /// /// Implementors of this trait must guarantee an element is always /// /// accessible with index 3. /// unsafe trait ThreeIndexable<T> { ///     /// Returns a reference to the element with index 3 in `&self`. ///     fn three(&self) -> &T; /// } /// /// // The implementation of `ThreeIndexable` for `[T; 4]` is `unsafe` /// // because the implementor must abide by a contract the compiler cannot /// // check but as a programmer we know there will always be a valid element /// // at index 3 to access. /// unsafe impl<T> ThreeIndexable<T> for [T; 4] { ///     fn three(&self) -> &T { ///         // SAFETY: implementing the trait means there always is an element ///         // with index 3 accessible. ///         unsafe { self.get_unchecked(3) } ///     } /// } /// /// let a = [1, 2, 4, 8]; /// assert_eq!(a.three(), &8); /// ``` /// /// [`extern`]: keyword.extern.html /// [`trait`]: keyword.trait.html /// [`static`]: keyword.static.html /// [`union`]: keyword.union.html /// [`impl`]: keyword.impl.html /// [Send]: marker/trait.Send.html /// [Sync]: marker/trait.Sync.html /// [`Vec::set_len`]: vec/struct.Vec.html#method.set_len /// [raw pointers]: ../reference/types/pointer.html </ins> /// [memory safety]: ../book/ch19-01-unsafe-rust.html <del> /// [not yet complete]: https://github.com/rust-lang/rust/issues/34601 </del> <ins> /// [Rustnomicon]: ../nomicon/index.html /// [nomicon-soundness]: ../nomicon/safe-unsafe-meaning.html /// [soundness]: https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#soundness-of-code--of-a-library /// [Reference]: ../reference/unsafety.html /// [proposal]: https://github.com/rust-lang/rfcs/pull/2585 /// [discussion on Rust Internals]: https://internals.rust-lang.org/t/what-does-unsafe-mean/6696 </ins> mod unsafe_keyword {} #[doc(keyword = "use")]