New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document all features in the reference #38643

Closed
chriskrycho opened this Issue Dec 28, 2016 · 46 comments

Comments

Projects
None yet
7 participants
@chriskrycho
Contributor

chriskrycho commented Dec 28, 2016

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:

  1. 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.
  2. 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."

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.)

  • #1131: Add an expect intrinsic
  • #1624: loop_break_value
  • #1665: Windows subsystem support

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

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

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 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.

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 priv keyword
  • #0059: Remove ~ in favor of box and Box
  • #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, Poly trait, 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 rustc bugfix 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)
@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Dec 28, 2016

A note on this: my plan is to spend some of my time between now and when I go back to work on Tuesday compiling the lists above. The goal will be to have an exhaustive list of items to tackle. Once we have those, I'll tackle the list piece by piece over the course of 2017; it's a personal goal of mine that when 2017 ends, the end-of-year blog post can say "We now have a fully up-to-date reference!" (I hope I'm not the only one working on it, too! But even if I am, I think we can get it done, slow but steady.)

Edit: this looks like it's going to take yet a bit longer than that. There's a lot to do in just determining the state of each item in the detailed way I am above. But we'll get there.

@brson

This comment has been minimized.

Contributor

brson commented Dec 29, 2016

Having a list to work off of will be a great start!

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Dec 30, 2016

Edit: moved all of this to the main issue.

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Dec 30, 2016

Is there a list of rfcs you are working from? Like a category for not yet looked at?

Edit: https://github.com/rust-lang/rfcs/tree/master/text, so how can we help?

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Dec 30, 2016

@Eh2406 that list is indeed the one, and thanks! If you want to start from the top after 0016 and work down, I'll start from the bottom and work up. You can just add them in an edit or a new comment, formatted similarly to what I have above, and I can then integrate that once we have the full list. Quite a few of those should be already documented.

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Dec 30, 2016

#0019 Is still being implomented. Not sure how to handle.

#0026 removes priv. So does not need docs, and is not in the reference.

Now back to work. I will continue as I have time.

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Dec 30, 2016

#0019 is… wow. Old, and moving slowly but steadily. Also going to require some work to figure out what the documentation status is!

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Dec 30, 2016

long live #20137

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Dec 30, 2016

It's prior art!

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Dec 30, 2016

#0034
looks to have bean implemented in #16432 altho thay seam to think it is #11. I don't entirely understand what it does but it seems that it changes when errors happen so I think it is ok on docs. I don't think it needs anything in the reference, but I don't understand it fully so I may be wrong.

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Dec 30, 2016

@Eh2406 ah, didn't realize you would have more time today, so I already looked at a couple more of those; see updated comment above!

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Dec 30, 2016

N.P. I didn't think I was going to have more time. :-P Are the notes I am making helpful? What would make them better?

#0040 is an oled reorganazation of std. I think the std docs are newer than this organization, so I think it is good.

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Dec 30, 2016

Help is appreciated; though see my comments on what is now the root of the issue re:both 0034 and 0040. 0034 is documented; 0040 isn't (at least, not sufficiently).

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Dec 30, 2016

I am skipping around to find ones that I can tell about.

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Dec 30, 2016

A bunch of things, now removed as incorporated in issue description.

Let me know if this was helpful, and what can be done to improve input. I will try and fined more time this weekend.

Even if none of this was helpful, I still got a lot out of skimming so many rfc's. (So don't be shy if it did not help.) Also sorry for the spelling mesticels.

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Dec 30, 2016

Thanks, @Eh2406! I'll review and let you know which pieces are most helpful and which need more info, but even just collating an overview of these ones is super helpful as triage. And I feel the same way about picking up a ton of knowledge just by skimming over them. (Imagine how much we'll know by the time we're done actually documenting all of these!)

@brson

This comment has been minimized.

Contributor

brson commented Dec 30, 2016

Wow @Eh2406 thanks for the research.

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Dec 31, 2016

@Eh2406 I've nearly following up on the ones you listed; thanks for doing the legwork on all of these! (If it has a 👍 on it from me, I've integrated it into the master list.)

To a few of the questions you raised:

First, all process RFCs can be left out of the Reference (though we should probably see to it that these things are easy to find somewhere).

style rfcs. do not need to be in the reference. Do they need docs?

I believe the intent is to capture the styles in a document for reference once they're all settled on (as the idea is to define a standard Rust style which rustfmt merely implements).

Removes the one-type-only restriction on format_args, dose this need to be in the Reference?

Nope, and in general anything that's a standard-library issue doesn't need to be in the reference. Obviously there are blurry spots where core and the language itself blur together (ops is one such example), but mostly library stuff doesn't need to be in the reference.

The memory model itself should certainly be documented; and when it lands, it should definitely go in the reference. But the creation of the strike team is just a process thing.

(I'll be noting each of those accordingly above, but figured they'd be helpful responses.)

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Jan 1, 2017

(though we should probably see to it that these things are easy to find somewhere).

I'd put this stuff on the forge.

I believe the intent is to capture the styles in a document for reference once they're all settled on (as the idea is to define a standard Rust style which rustfmt merely implements).

Yes, and this would be separate from the language reference.

@tinaun

This comment has been minimized.

Contributor

tinaun commented Jan 1, 2017

some more:

implemented

#0049 - allows attributes in match arms. technically documented in section 6.3 of the reference, but it could be made more explicit that rust allows attributes "inside" enums, structs, matches, etc.

#0050 - adds debug_assert!. documented in std.

#0059 - StrBuf -> String. no documentation needed.

#0063 - tightens the module loading requirements to prevent needless imports. not documented. might not need to be, as it just removes formerly legal mod foo; declarations

#0068 *T -> *const T. no documentation needed.

#0069 adds byte string and character literals (eg b"foo", b'?'). documented in section 3.5.1.3

open

#0066 - better temporary lifetimes, to lessen the need to split method chains into their own let statements. hasn't seen much progress since the rfc was approved.

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Jan 2, 2017

Now that we have some examples under our belt I want to try and be a literal clearer about what we are trying to determine about each RFC. I think it is:

  1. Is the RFC Retired/Removals/Process/conventions?
    If sow, Report on which one, a linke, and a short sentence of description.
  2. Else Is the RFC not yet implemented?
    If yes or to complicated to tell, Report on a linke, and a short sentence of description, as it goes in 0.
  3. Else Is the RFC not yet stabilized?
    If yes, Report on a linke, and a short sentence of description, as it goes in 0.
  4. Else
  • Is the RFC in the Reference?
    If yes, Report on whether the description is adequate?
    If not, Report on whether it needs to be?
  • Is the RFC in the STD docs?
    If yes, Report on whether the description is adequate?
    If not, Report on whether it needs to be?
  • Is the RFC in the Book?
    If yes, Report on whether the description is adequate?
    If not, Report on whether it needs to be?

I will have some time tomorrow morning. I will try and follow this formula unless someone has some better advice. ... on second thought, 4 sounds difficult. So I will probably go thru the list looking for RFC's that fall into 1-3. :-)

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Jan 2, 2017

Thanks, @tinaun – integrating those into the list now!

Great summary, @Eh2406. One thing I'd add: we don't need to worry about open PRs. So e.g. Steve's Bookshelf PR isn't merged yet, and as such wouldn't need to be documented even if it weren't a process PR.

You folks' helping out with this is super valuable. Thanks!

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Jan 2, 2017

@steveklabnik:

I'd put this stuff on the forge.

Seems good. As noted, we should get a link to the forge added to the documentation page. I'm happy to submit a PR accordingly, though the way that's currently organized suggests that it might need a new section?

Re: style guide—

Yes, and this would be separate from the language reference.

👍 Yep, I see that wasn't obvious in my writeup, but that's definitely what I had in mind. It presumably should be linked from the documentation page, as well.

All of that suggests to me that #1828 (assuming acceptance) could be well-complemented by thinking further about the design and information architecture of how we present docs to user—but that's definitely for another issue!

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Jan 2, 2017

though the way that's currently organized suggests that it might need a new section?

Possibly, send one in for whatever you think is best and we can discuss it in-PR.

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Jan 2, 2017

I tried for breadth over depth. So I opened each and spent approx 30 sec to put it in a category. At that speed mistakes were made. Entries within categories are left in number order.

https://gist.github.com/Eh2406/57e9b7d4d2be1dd11eb400de9c65ec8f

@alanstoate

This comment has been minimized.

Contributor

alanstoate commented Jan 5, 2017

Already Documented

1054-str-words.md
Documented in: std
str::words() changed to str::split_whitespace()

1057-io-error-sync.md
Documented in: std
io::error includes Sync bound

1058-slice-tail-redesign.md
Documented in: std
slice.tail(), slice.init() changed to slice.split_first(), slice.split_last()

1066-safe-mem-forget.md
Documented in: std
unsafe not in mem::forget signature
explicitly stated that it is unsafe

1102-rename-connect-to-join.md
Documented in: std
SliceConcatExt::join added
SliceConcatExt::connect marked as deprecated

1119-result-expect.md
Documented in: std
result::Result::excpect added

1123-str-split-at.md
Documented in: std
str::split_at added

Implemented, Unstable

1131-likely-intrinsic.md
implemented but not stabilized #26179

Process RFCs

1068-rust-governance.md
Splitting the team into subteams

1105-api-evolution.md
API versioning guidelines

1122-language-semver.md
rust language versioning guidelines

Removals

1096-remove-static-assert.md

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Jan 5, 2017

Awesome work, @Eh2406 and @alanstoate! I'll see about integrating those into the primary post over the weekend.

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Jan 10, 2017

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Jan 19, 2017

ping?

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Jan 19, 2017

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Jan 27, 2017

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Jan 27, 2017

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Jan 27, 2017

@Emilgardis

This comment has been minimized.

Emilgardis commented Jan 28, 2017

Some features are added without any rfc process, how should these cases be handled?
Example: cfg and attributes on struct fields #38814

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Jan 28, 2017

@Emilgardis Granted that I'm not in charge, but I assume the RFC covers those as well. Small features are still features. I focused on RFCs because those are where the large changes come in, and where the biggest gaps are, but that's definitely worth clarifying.

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Feb 1, 2017

Would it help if I move my not-yet-incorporated Triaged into a gist? It would shorten this long conversation, give you access to the raw markdown, and allow you to mark incremental changes as you incorporate them.

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Feb 1, 2017

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Feb 8, 2017

I've now processed everything other than @Eh2406's Gists. So: roughly a fifth of the way there! But those should go relatively quickly, thanks to that fabulous preparation. More to come in the days and weeks ahead!

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Feb 8, 2017

Feel free to fork the Gist and remove items as they are incorporated. I have found it very liberating to move things one at a time. Also all the links go to the same Gist, so it is not so scary.

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Feb 8, 2017

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Feb 20, 2017

I merged your changes, I love how gists are repos in disguise, then used a regex to reformat all the remaining links to look more like the ones in your post.

@steveklabnik steveklabnik removed the T-doc label Mar 10, 2017

@Eh2406

This comment has been minimized.

Contributor

Eh2406 commented Mar 10, 2017

@chriskrycho ping?

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Mar 10, 2017

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Mar 10, 2017

@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Mar 10, 2017

@chriskrycho chriskrycho referenced this issue Mar 11, 2017

Closed

Document all features #9

18 of 48 tasks complete
@chriskrycho

This comment has been minimized.

Contributor

chriskrycho commented Mar 11, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment