You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Tracking issue for RFC #1636. Let's make the reference a reliable resource for all Rustaceans! 🎉 This might seem intimidating, but the reality is that if we just chip away at it together, we'll be done in no time!
I'm going to be updating this parent issue with a master list of items that need to be documented in the reference as I find them. Quoting the RFC text:
Updating the reference should proceed stepwise:
Begin by adding an appendix in the reference with links to all accepted RFCs which have been implemented but are not yet referenced in the documentation.
As the reference material is written for each of those RFC features, remove it from that appendix.
Note that step 1 should be fairly straightforward; the main issue will be assembling the list of accepted-and-implemented-but-undocumented RFCs. (Also, any RFCs accepted before RFC 1636 but not yet stabilized should presumably be documented under the rules it establishes, but if I'm wrong about that, someone should let me know and I'll include them as well.)
Also, a pre-emptive apology for the scale of this issue description. We have let things get into a rough spot. (I plan to create documentation issues for each of the required items below once this list is completed, so this thread doesn't become completely unmanageable.)
For right now, since you can't submit updates to the issue directly, there are two major ways you can help:
Write documentation. For the RFCs already triaged and filed under the major section C. Documentation Needed and specifically the subsection 2. Write reference material for undocumented, implemented, stabilized RFC features below, you can open a pull request and reference this issue in its description. I'll keep an eye out for inbound links here and add those links to the relevant items, and once they're merged, we'll mark that item as done.
Triage issues. Work the gist where I'm tracking the triaged-state, specifically looking at the Not Reviewed at All and Stabilized, Not Reviewed sections and evaluating whether they're documented or not. You can fork the gist and I will keep an eye out, checking roughly daily, for any changes to merge back into that document. (Do take a look at what others may have forked it so you don't duplicate work needlessly!) I'll then pull those over into this master issue.
When working through those, if you determine that they're already documented, please leave a note (and link!) on your copy of the gist as to where so I can link it in this document. That dramatically decreases the time it takes me to confirm it—I double-check all of these.
A. Tracking
(This section will go away entirely once all of the RFCs have been flagged for documenting or marked documentation-not-needed here.)
1510-cdylib.md Rename 1510-rdylib.md to 1510-cdylib.md
1513-less-unwinding.md
1521-copy-clone-semantics.md
1522-conservative-impl-trait.md
1525-cargo-workspace.md
1535-stable-overflow-checks.md
1542-try-from.md
1543-integer_atomics.md
1548-global-asm.md
1552-contains-method-for-various-collections.md
1559-attributes-with-literals.md
1560-name-resolution.md
1561-macro-naming.md
1581-fused-iterator.md
1623-static.md
1649-atomic-access.md
1653-assert_ne.md
1660-try-borrow.md
1679-panic-safe-slicing.md
1681-macros-1.1.md
1682-field-init-shorthand.md
1696-discriminant.md
1717-dllimport.md
B. Status unclear
Some of these are still in-flight; and some of them are just the kind of thing that I don't even fully grok yet well enough to see if they're documented. For these, unchecked means "status unknown"; checked means "status known and added to the latter bits appropriately."
These should be considered the highest priority for documentation, as these are issues which fall under the rest of the rules of [RFC #1636], in that they need to be documented before stabilization. (That will presumably just happen before stabilizing as usual, but I'm including them here for completeness.)
1. List accepted, implemented, already-stabilized, undocumented RFCs
This list can be added directly to a newly(-to-be)-created appendix to the Reference.
Create the appendix (once finished, this list should do just fine, perhaps with some massaging for descriptiveness)
#0040: libstd-facade – there is one reference to the facade, in 6.3.13 Compiler Features under a discussion of #[no_std], but no explanation of its meaning. Nor, as far as I can tell, do the relevant sections of the standard library documentation explain this.
#0048: Trait reform – some pieces of this are partially documented (the use of Self), but others aren't at all: coherence and orphan rules are covered nowhere. (Currently, the writeup here seems to be the best source on coherence?)
#0049: Allow attributes on match arms. – the underlying idea is documented in 6.3 Attributes but the applicability to internal items is never specified.
#0164: Feature gate pattern-matching on slices; documented as feature-flagged and unstable at 6.3.13 Compiler features.
#0390: Define variants in a sub-namespace of their enum; clear from all examples at 6.1.6 Enumerations and in the book, and explicit in the discussion of paths in 6.1 Items.
#0403: Cargo build command—not, strictly speaking, a language detail; and documented in the book and at doc.crates.io.
#0565: Renaming fmt::Show and fmt::String to fmt::Debug and fmt::Display respectively, along with where to implement them; documented in the entire standard library as well as specifically at std::fmt::Debug and std::fmt::Display
#1054: change str::words() to str::split_whitespace(), documented in std
#1057: add the Sync bound to io::Error, documented at std::io::Error
#1058: replace slice.tail(), slice.init() with slice.split_first(), slice.split_last(), documented at slice
#1066: change std::mem::forget not to be unsafe (though it is not safe), behavior is carefully and fully documented at std::mem::forget
#1102: replace SliceConcatExt::connect with SliceConcatExt::join, documented in std
#1119: add result::Result::expect() method, documented in std
#1123: add str::split_at() method, documented in std
#1618: relax format_args! type restrictions, documented in std
#1620: regex-1.0, documented in-tree at the crate docs (this is a library issue, not a reference issue)
#0112: Remove cross borrowing coercion. Replaced by the removal in #0139.
#0115: do not fall back to int if cannot infer integer; replaced with #0212.
#0155: only allow "anonymous impl" (impl Foo) in the same module as the data type is defined (struct Foo or mod Foo). Replaced by #0735.
2. Removals
Some items constitute not *additions to be documented* but *things removed* from the language. These do not require documentation (for obvious reasons!).
Some changes are specific to the parsing (though they affect the language). These should be documented not in the reference but in the language grammar.
#1242: Policy for rust-lang GitHub organization crates governance
#1331: grammar: make the formal grammer canonical and formal – Note: I think this should probably be linked in the reference (as well as other places) once it's finished, and it's already linked from the head of the reference.
#1567: Normalize long error codes with a baseline template
Note: I've just copied over the original issue as it was—wholesale. Note that some of the links here referencing things as "already documented" will degrade given the new structure of the book.
Overview
Tracking issue for RFC #1636. Let's make the reference a reliable resource for all Rustaceans! 🎉 This might seem intimidating, but the reality is that if we just chip away at it together, we'll be done in no time!
I'm going to be updating this parent issue with a master list of items that need to be documented in the reference as I find them. Quoting the RFC text:
Note that step 1 should be fairly straightforward; the main issue will be assembling the list of accepted-and-implemented-but-undocumented RFCs. (Also, any RFCs accepted before RFC 1636 but not yet stabilized should presumably be documented under the rules it establishes, but if I'm wrong about that, someone should let me know and I'll include them as well.)
Also, a pre-emptive apology for the scale of this issue description. We have let things get into a rough spot. (I plan to create documentation issues for each of the required items below once this list is completed, so this thread doesn't become completely unmanageable.)
Status: Last updated May 13, 2017, now processing a copy of @Eh2406's wonderful gist based on @matthewjasper's fork here.
"How Can I Help?"
For right now, since you can't submit updates to the issue directly, there are two major ways you can help:
Write documentation. For the RFCs already triaged and filed under the major section C. Documentation Needed and specifically the subsection 2. Write reference material for undocumented, implemented, stabilized RFC features below, you can open a pull request and reference this issue in its description. I'll keep an eye out for inbound links here and add those links to the relevant items, and once they're merged, we'll mark that item as done.
Triage issues. Work the gist where I'm tracking the triaged-state, specifically looking at the Not Reviewed at All and Stabilized, Not Reviewed sections and evaluating whether they're documented or not. You can fork the gist and I will keep an eye out, checking roughly daily, for any changes to merge back into that document. (Do take a look at what others may have forked it so you don't duplicate work needlessly!) I'll then pull those over into this master issue.
When working through those, if you determine that they're already documented, please leave a note (and link!) on your copy of the gist as to where so I can link it in this document. That dramatically decreases the time it takes me to confirm it—I double-check all of these.
A. Tracking
(This section will go away entirely once all of the RFCs have been flagged for documenting or marked documentation-not-needed here.)
RFCs reviewed
Currently: 115/301
Details
RFCs unreviewed
Details
B. Status unclear
Some of these are still in-flight; and some of them are just the kind of thing that I don't even fully grok yet well enough to see if they're documented. For these, unchecked means "status unknown"; checked means "status known and added to the latter bits appropriately."
C. Documentation needed
0. Accepted, not-yet-stabilized, undocumented RFCs
0.1. Document implemented, unstable RFCs
These should be considered the highest priority for documentation, as these are issues which fall under the rest of the rules of [RFC #1636], in that they need to be documented before stabilization. (That will presumably just happen before stabilizing as usual, but I'm including them here for completeness.)
plugin-registrarAPIrepr_align– implementation is in-progress, not yet landed on nightlyloop_break_value0.2. Track accepted, not-yet-implemented or implementation-in-progress, undocumented RFCs
These will eventually require documentation, but as they aren't even (fully) implemented yet, there is no urgency here.
{Vec,String}::splice– tracking issuemacro_rules!– tracking issuemacro_rules– tracking issueshared_from_slice– tracking issueManuallyDropto core – tracking issueeprint!andeprintln!– tracking issue1. List accepted, implemented, already-stabilized, undocumented RFCs
This list can be added directly to a newly(-to-be)-created appendix to the Reference.
Create the appendix (once finished, this list should do just fine, perhaps with some massaging for descriptiveness)
libstd-facade– there is one reference to the facade, in 6.3.13 Compiler Features under a discussion of#[no_std], but no explanation of its meaning. Nor, as far as I can tell, do the relevant sections of the standard library documentation explain this.Self), but others aren't at all: coherence and orphan rules are covered nowhere. (Currently, the writeup here seems to be the best source on coherence?)crt_linkunaligned_access2. Write reference material for undocumented, implemented, stabilized RFC features
Each of the features listed above in (1) needs to be documented more formally in the reference.
libstd-facadeextern "stdcall"on non-x86 #71]: ([WIP] Expressions rewrite #13) Allow blocks in constants&mutpatterns – symmetry of pattern syntax not documentedcrt_linkunaligned_access3. Update out-of-date/incomplete sections of the reference
List of language items
Coherence
Orphan rules (Document Orphan Rules #5)
Lifetime elision
D. Documentation not needed
0. Already documented
Details
std.debug_assert!andassert!; documented atstd::debug_assertandstd::assert.StrBuftoString; documented atstd::string::Stringandcollections::string::String.*Tto*const T; documented at 8.1.8 Pointer typesSharetrait; documented atstd::marker::Syncwhereclasses; documented at 6.1.3.1 Generic functions and discussed thoroughly in both the current and upcoming versions of the book.while letloops; documented at 7.2.24while letloops.buildcommand—not, strictly speaking, a language detail; and documented in the book and at doc.crates.io.tuple_indexing,if_let, andwhile_let, documented at 8.1.3 Tuple types, 7.2.23if letexpressions, 7.2.24while letloops.[T; N]and[x; N], documented in 8.1.4 Array and Slice types.inttousize/isize, documented in 8.1.1.2 Machine-dependent integer typesndebugconfig variable – replaced withdebug_assertions, documented at 6.3.8 Conditional Compilationfmt::Showandfmt::Stringtofmt::Debugandfmt::Displayrespectively, along with where to implement them; documented in the entire standard library as well as specifically atstd::fmt::Debugandstd::fmt::Displaystr::words()tostr::split_whitespace(), documented instdSyncbound toio::Error, documented atstd::io::Errorslice.tail(),slice.init()withslice.split_first(),slice.split_last(), documented atslicestd::mem::forgetnot to beunsafe(though it is not safe), behavior is carefully and fully documented atstd::mem::forgetSliceConcatExt::connectwithSliceConcatExt::join, documented instdresult::Result::expect()method, documented instdstr::split_at()method, documented instdformat_args!type restrictions, documented instdduration_checked, documented instd1. Retired
These items were accepted, but never implemented and not currently *planned* to be implemented and therefore not in need of documentation.
intif cannot infer integer; replaced with #0212.impl Foo) in the same module as the data type is defined (struct Fooormod Foo). Replaced by #0735.2. Removals
Some items constitute not *additions to be documented* but *things removed* from the language. These do not require documentation (for obvious reasons!).
privkeyword~in favor ofboxandBoxmodformat!Gc<T>from stdliblibdebug,Polytrait, and an earlier version of:?, since repurposed)static_assert3. Parser-specific
Some changes are specific to the parsing (though they affect the language). These should be documented not in the reference but in the language grammar.
4. Process and conventions
Details
Io:Error, notIo::IoError)unwraprustcbugfix best practices5. Non-language features
Details
Note: I've just copied over the original issue as it was—wholesale. Note that some of the links here referencing things as "already documented" will degrade given the new structure of the book.