Closed
Description
Last updated February 10, 2017, now processing a fork of @Eh2406's wonderful gist.
Tracking issue for RFC #1636. 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.)
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: 75/291
- 0001-private-fields.md
- 0002-rfc-process.md
- 0003-attribute-usage.md
- 0008-new-intrinsics.md
- 0016-more-attributes.md
- 0019-opt-in-builtin-traits.md
- 0026-remove-priv.md
- 0034-bounded-type-parameters.md
- 0040-libstd-facade.md
- 0042-regexps.md
- 0048-traits.md
- 0049-match-arm-attributes.md
- 0050-assert.md
- 0059-remove-tilde.md
- 0060-rename-strbuf.md
- 0063-module-file-system-hierarchy.md
- 0066-better-temporary-lifetimes.md
- 0068-const-unsafe-pointers.md
- 0069-ascii-literals.md
- 0093-remove-format-intl.md
- 0109-remove-crate-id.md
- 0112-remove-cross-borrowing.md
- 0115-rm-integer-fallback.md
- 0123-share-to-threadsafe.md
- 0135-where.md
- 0139-remove-cross-borrowing-entirely.md
- 0155-anonymous-impl-only-in-same-module.md
- 0164-feature-gate-slice-pats.md
- 0199-ownership-variants.md
- 0214-while-let.md
- 0230-remove-runtime.md
- 0235-collections-conventions.md
- 0236-error-conventions.md
- 0256-remove-refcounting-gc-of-t.md
- 0341-remove-virtual-structs.md
- 0379-remove-reflection.md
- 0385-module-system-cleanup.md
- 0390-enum-namespacing.md
- 0403-cargo-build-command.md
- 0446-es6-unicode-escapes.md
- 0450-un-feature-gate-some-more-gates.md
- 0507-release-channels.md
- 0520-new-array-repeat-syntax.md
- 0531-define-rfc-scope.md
- 0533-no-array-elem-moves.md
- 0544-rename-int-uint.md
- 0558-require-parentheses-for-chained-comparisons.md
- 0560-integer-overflow.md
- 0563-remove-ndebug.md
- 1054-str-words.md
- 1057-io-error-sync.md
- 1058-slice-tail-redesign.md
- 1066-safe-mem-forget.md
- 1068-rust-governance.md
- 1096-remove-static-assert.md
- 1102-rename-connect-to-join.md
- 1105-api-evolution.md
- 1119-result-expect.md
- 1122-language-semver.md
- 1123-str-split-at.md
- 1131-likely-intrinsic.md
- 1589-rustc-bug-fix-procedure.md
- 1607-style-rfcs.md
- 1618-ergonomic-format-args.md
- 1620-regex-1.0.md
- 1624-loop-break-value.md
- 1636-document_all_features.md
- 1640-duration-checked-sub.md
- 1643-memory-model-strike-team.md
- 1644-default-and-expanded-rustc-errors.md
- 1665-windows-subsystem.md
- 1683-docs-team.md
- 1721-crt-static.md
- 1725-unaligned-access.md
- 1728-north-star.md
RFCs unreviewed
- 0071-const-block-expr.md
- 0079-undefined-struct-layout.md
- 0085-pattern-macros.md
- 0086-plugin-registrar.md
- 0087-trait-bounds-with-plus.md
- 0089-loadable-lints.md
- 0090-lexical-syntax-simplification.md
- 0092-struct-grammar.md
- 0100-partial-cmp.md
- 0107-pattern-guards-with-bind-by-move.md
- 0111-index-traits.md
- 0114-closures.md
- 0116-no-module-shadowing.md
- 0130-box-not-special.md
- 0131-target-specification.md
- 0132-ufcs.md
- 0136-no-privates-in-public.md
- 0141-lifetime-elision.md
- 0151-capture-by-value.md
- 0160-if-let.md
- 0168-mod.md
- 0169-use-path-as-id.md
- 0179-and-mut-patterns.md
- 0184-tuple-accessors.md
- 0192-bounds-on-object-and-generic-types.md
- 0194-cfg-syntax.md
- 0195-associated-items.md
- 0198-slice-notation.md
- 0201-error-chaining.md
- 0202-subslice-syntax-change.md
- 0212-restore-int-fallback.md
- 0213-defaulted-type-params.md
- 0216-collection-views.md
- 0218-empty-struct-with-braces.md
- 0221-panic.md
- 0231-upvar-capture-inference.md
- 0234-variants-namespace.md
- 0240-unsafe-api-location.md
- 0241-deref-conversions.md
- 0243-trait-based-exception-handling.md
- 0246-const-vs-static.md
- 0255-object-safety.md
- 0320-nonzeroing-dynamic-drop.md
- 0326-restrict-xXX-to-ascii.md
- 0339-statically-sized-literals.md
- 0342-keywords.md
- 0344-conventions-galore.md
- 0356-no-module-prefixes.md
- 0369-num-reform.md
- 0378-expr-macros.md
- 0380-stabilize-std-fmt.md
- 0387-higher-ranked-trait-bounds.md
- 0401-coercions.md
- 0404-change-prefer-dynamic.md
- 0418-struct-variants.md
- 0430-finalizing-naming-conventions.md
- 0438-precedence-of-plus.md
- 0439-cmp-ops-reform.md
- 0445-extension-trait-conventions.md
- 0447-no-unused-impl-parameters.md
- 0453-macro-reform.md
- 0458-send-improvements.md
- 0459-disallow-shadowing.md
- 0461-tls-overhaul.md
- 0463-future-proof-literal-suffixes.md
- 0469-feature-gate-box-patterns.md
- 0474-path-reform.md
- 0486-std-ascii-reform.md
- 0490-dst-syntax.md
- 0494-c_str-and-c_vec-stability.md
- 0495-array-pattern-changes.md
- 0501-consistent_no_prelude_attributes.md
- 0503-prelude-stabilization.md
- 0504-show-stabilization.md
- 0505-api-comment-conventions.md
- 0509-collections-reform-part-2.md
- 0517-io-os-reform.md
- 0522-self-impl.md
- 0526-fmt-text-writer.md
- 0528-string-patterns.md
- 0529-conversion-traits.md
- 0532-self-in-use.md
- 0534-deriving2derive.md
- 0546-Self-not-sized-by-default.md
- 0550-macro-future-proofing.md
- 0556-raw-lifetime.md
- 0565-show-string-guidelines.md
- 0572-rustc-attribute.md
- 0574-drain-range.md
- 0580-rename-collections.md
- 0587-fn-return-should-be-an-associated-type.md
- 0592-c-str-deref.md
- 0593-forbid-Self-definitions.md
- 0599-default-object-bound.md
- 0601-replace-be-with-become.md
- 0639-discriminant-intrinsic.md
- 0640-debug-improvements.md
- 0702-rangefull-expression.md
- 0735-allow-inherent-impls-anywhere.md
- 0736-privacy-respecting-fru.md
- 0738-variance.md
- 0769-sound-generic-drop.md
- 0771-std-iter-once.md
- 0803-type-ascription.md
- 0809-box-and-in-for-stdlib.md
- 0823-hash-simplification.md
- 0832-from-elem-with-love.md
- 0839-embrace-extend-extinguish.md
- 0840-no-panic-in-c-string.md Update 0840-no-panic-in-c-string.md
- 0873-type-macros.md
- 0879-small-base-lexing.md
- 0888-compiler-fence-intrinsics.md
- 0909-move-thread-local-to-std-thread.md
- 0911-const-fn.md
- 0921-entry_v3.md
- 0940-hyphens-considered-harmful.md
- 0953-op-assign.md
- 0968-closure-return-type-syntax.md
- 0979-align-splitn-with-other-languages.md
- 0980-read-exact.md
- 0982-dst-coercion.md
- 1011-process.exit.md
- 1014-stdout-existential-crisis.md
- 1023-rebalancing-coherence.md
- 1030-prelude-additions.md
- 1040-duration-reform.md
- 1044-io-fs-2.1.md
- 1047-socket-timeouts.md
- 1048-rename-soft-link-to-symlink.md
- 1135-raw-pointer-comparisons.md
- 1152-slice-string-symmetry.md
- 1156-adjust-default-object-bounds.md
- 1174-into-raw-fd-socket-handle-traits.md
- 1183-swap-out-jemalloc.md
- 1184-stabilize-no_std.md
- 1191-hir.md
- 1192-inclusive-ranges.md
- 1193-cap-lints.md
- 1194-set-recovery.md
- 1199-simd-infrastructure.md
- 1200-cargo-install.md
- 1201-naked-fns.md
- 1210-impl-specialization.md
- 1211-mir.md
- 1212-line-endings.md
- 1214-projections-lifetimes-and-wf.md
- 1216-bang-type.md
- 1219-use-group-as.md
- 1228-placement-left-arrow.md
- 1229-compile-time-asserts.md
- 1236-stabilize-catch-panic.md
- 1238-nonparametric-dropck.md
- 1240-repr-packed-unsafe-ref.md
- 1241-no-wildcard-deps.md
- 1242-rust-lang-crates.md
- 1252-open-options.md
- 1257-drain-range-2.md
- 1260-main-reexport.md
- 1268-allow-overlapping-impls-on-marker-traits.md
- 1270-deprecation.md
- 1288-time-improvements.md
- 1291-promote-libc.md
- 1298-incremental-compilation.md
- 1300-intrinsic-semantics.md
- 1307-osstring-methods.md
- 1317-ide.md
- 1327-dropck-param-eyepatch.md
- 1328-global-panic-handler.md
- 1331-grammar-is-canonical.md
- 1358-repr-align.md
- 1359-process-ext-unix.md
- 1361-cargo-cfg-dependencies.md Add extension ".md
- 1398-kinds-of-allocators.md
- 1399-repr-pack.md
- 1415-trim-std-os.md
- 1419-slice-copy.md
- 1422-pub-restricted.md
- 1432-replace-slice.md
- 1434-contains-method-for-ranges.md
- 1440-drop-types-in-const.md
- 1443-extended-compare-and-swap.md
- 1444-union.md
- 1445-restrict-constants-in-patterns.md Remove duplicate 0000-restrict-constants-in-patterns.md
- 1461-net2-mutators.md
- 1467-volatile.md
- 1479-unix-socket.md
- 1492-dotdot-in-patterns.md
- 1498-ipv6addr-octets.md
- 1504-int128.md
- 1506-adt-kinds.md
- 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
- 1566-proc-macros.md
- 1567-long-error-codes-explanation-normalization.md
- 1574-more-api-documentation-conventions.md
- 1576-macros-literal-matcher.md
- 1581-fused-iterator.md
- 1590-macro-lifetimes.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
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."
- #0019: Opt-in built-in traits (OIBITs)
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.)
0.2 Track accepted, not-yet-implemented, undocumented RFCs
These will eventually require documentation, but as they aren't even implemented yet, there is no urgency here.
- #0066: Better temporary lifetimes
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
- #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.
- #0558: require parentheses for chained comparisons
- #0560: Integer overflow not unsafe, documented with a reference to the RFC but requires further details
- #1717: dllimport, one element mentioned but not explained at 6.3.5 FFI attributes
- #1721: define
crt_link - #1725: define
unaligned_access
- #0040:
2. 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.
- #0040:
libstd-facade - #0048: Trait reform, requires documenting coherence and orphan rules (overlaps with Coherence and Orphan rules below in §3)
- #0049: Allow attributes on match arms: specify applicability to internal items
- #0558: require parentheses for chained comparisons -- the requirement is not documented in the reference
- #0560: Integer overflow not unsafe, documented with a reference to the RFC but requires further details
- #1717: dllimport
- #1721:
crt_link - #1725:
unaligned_access
3. Update out-of-date/incomplete sections of the reference
-
List of language items
The set of language items is currently considered unstable. A complete list of the built-in language items will be added in the future.
-
Coherence
-
Orphan rules
-
Lifetime elision
Documentation not needed
Already documented
- #0001: Private fields by default, in 6.2 Visibility and Privacy
- #0003: Rearchitect the attribute-usage lint, in 6.3 Attributes
- #0016: attributes on statements and blocks, in 6.3 Attributes
- #0034: well-formed trait bounds, in 6.1.9 Traits
- #0042: regexp crate – library documented here; could also be treated as Retired since it's currently still part of the nursery and not part of
std. - #0050: adds
debug_assert!andassert!; documented atstd::debug_assertandstd::assert. - #0060: rename
StrBuftoString; documented atstd::string::Stringandcollections::string::String. - #0068: change
*Tto*const T; documented at 8.1.8 Pointer types - #0069: add ASCII byte literals and ASCII byte string literals to the language; documented at 3.5.1.3 Byte and byte string literals
- #0109; documented at 5 Crates and source files and used as part of an example in the current Rust book (Custom Allocators)
- #0123: rename
Sharetrait; documented atstd::marker::Sync - #0135:
whereclasses; documented at 6.1.3.1 Generic functions and discussed thoroughly in both the current and upcoming versions of the book. - #0214:
while letloops; documented at 7.2.24while letloops. - #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
buildcommand—not, strictly speaking, a language detail; and documented in the book and at doc.crates.io. - #0446: ES6-style unicode string escaping, documented at 3.5.1.1.3 Unicode escapes.
- #0450: Un-feature-gate
tuple_indexing,if_let, andwhile_let, documented at 8.1.3 Tuple types, 7.2.23if letexpressions, 7.2.24while letloops. - #0520: Array syntax
[T; N]and[x; N], documented in 8.1.4 Array and Slice types. - #0544: Rename
inttousize/isize, documented in 8.1.1.2 Machine-dependent integer types - #0563: Remove
ndebugconfig variable -- replaced withdebug_assertions, documented at 6.3.8 Conditional Compilation - #1054: change
str::words()tostr::split_whitespace(), documented instd - #1057: add the
Syncbound toio::Error, documented atstd::io::Error - #1058: replace
slice.tail(),slice.init()withslice.split_first(),slice.split_last(), documented atslice - #1066: change
std::mem::forgetnot to beunsafe(though it is not safe), behavior is carefully and fully documented atstd::mem::forget - #1102: replace
SliceConcatExt::connectwithSliceConcatExt::join, documented instd - #1119: add
result::Result::expect()method, documented instd - #1123: add
str::split_at()method, documented instd - #1618: relax
format_args!type restrictions, documented instd - #1620: regex-1.0, documented in-tree at the crate docs (this is a library issue, not a reference issue)
- #1640:
duration_checked, documented instd
Retired
These items were accepted, but never implemented and not currently planned to be implemented and therefore not in need of documentation.
- #0008: New intrinsics
- #0112: Remove cross borrowing coercion. Replaced by the removal in #0139.
- #0115: do not fall back to
intif cannot infer integer; replaced with #0212. - #0155: only allow "anonymous impl" (
impl Foo) in the same module as the data type is defined (struct Fooormod Foo). Replaced by #0735.
Removals
Some items constitute not additions to be documented but things removed from the language. These do not require documentation (for obvious reasons!).
- #0026: Remove the
privkeyword - #0059: Remove
~in favor ofboxandBox - #0063: Tighten restrictions on
mod - #0093: Remove localization from
format! - #0139: Remove cross borrowing entirely.
- #0230: Remove runtime
- #0256: Remove refcounting
Gc<T>from stdlib - #0341: Remove "virtual struct"/struct inheritance feature
- #0379: Remove reflection (
libdebug,Polytrait, and an earlier version of:?, since repurposed) - #0385: Module system cleanup and simplification (current module rules are documented; these changes removed restrictions)
- #0533: Remove support for moving individual elements into uninitialized arrays or out of fixed-sized arrays
- #1096: Remove
static_assert
Process and conventions
- #0199: Conventions for ownership variants (naming conventions, mostly internal interest)
- #0235: Conventions for collections and iterables (and a few other things)
- #0236: Conventions for error handling
- #0507: Release channels
- #0531: RFC scope and Rust "distribution" definition
- #1068: Scaling Rust's governance
- #1105: API evolution and versioning guidelines
- #1122: Rust language SemVer definitions
- #1589: Define the
rustcbugfix best practices - #1607: RFC process for formatting style and Rustfmt defaults (results will be captured in a non-reference document)
- #1636: Document All Features (process) (this PR!)
- #1643: Dedicated strike team to resolve unsafe code guidelines (results should be captured in the Reference, but this issue itself not so much)
- #1644: Default and expanded errors for rustc
- #1683: Create a docs subteam
- #1728: North Star (process)