Document all features in the reference #38643

Open
chriskrycho opened this Issue Dec 28, 2016 · 41 comments

Projects

None yet

7 participants

@chriskrycho
Contributor
chriskrycho commented Dec 28, 2016 edited

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
Contributor
chriskrycho commented Dec 28, 2016 edited

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
Contributor
brson commented Dec 29, 2016

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

@chriskrycho
Contributor
chriskrycho commented Dec 30, 2016 edited

Edit: moved all of this to the main issue.

@Eh2406
Eh2406 commented Dec 30, 2016 edited

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
Contributor

@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
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
Contributor

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

@chriskrycho chriskrycho referenced this issue Dec 30, 2016
Open

opt-in built-in bounds traits RFC tracker #13231

15 of 19 tasks complete
@steveklabnik
Contributor

long live #20137

@chriskrycho
Contributor

It's prior art!

@Eh2406
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
Contributor

@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
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
Contributor

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
Eh2406 commented Dec 30, 2016 edited

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

@Eh2406
Eh2406 commented Dec 30, 2016 edited

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
Contributor

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
Contributor
brson commented Dec 30, 2016

Wow @Eh2406 thanks for the research.

@chriskrycho
Contributor
chriskrycho commented Dec 31, 2016 edited

@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
Contributor

(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
Contributor
tinaun commented Jan 1, 2017 edited

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
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
Contributor
chriskrycho commented Jan 2, 2017 edited

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
Contributor

@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
Contributor

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
Eh2406 commented Jan 2, 2017 edited

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

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
Contributor

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

@Eh2406
Eh2406 commented Jan 19, 2017

ping?

@chriskrycho
Contributor
@Eh2406
Eh2406 commented Jan 27, 2017 edited
@chriskrycho
Contributor
@Emilgardis

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

@chriskrycho
Contributor

@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
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
Contributor
@chriskrycho
Contributor

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
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
Contributor
@Eh2406
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.

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