Document all features in the reference #38643
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:
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.)
(This section will go away entirely once all of the RFCs have been flagged for documenting or marked documentation-not-needed here.)
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."
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.
1. List accepted, implemented, already-stabilized, undocumented RFCs
This list can be added directly to a newly(-to-be)-created appendix to the Reference.
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.
3. Update out-of-date/incomplete sections of the reference
Documentation not needed
These items were accepted, but never implemented and not currently planned to be implemented and therefore not in need of documentation.
Some items constitute not additions to be documented but things removed from the language. These do not require documentation (for obvious reasons!).
Process and conventions
The text was updated successfully, but these errors were encountered:
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.
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?
@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.
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.
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!)
@Eh2406 I've nearly following up on the ones you listed; thanks for doing the legwork on all of these! (If it has a
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).
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
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
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.)
I'd put this stuff on the forge.
Yes, and this would be separate from the language reference.
#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
#0063 - tightens the module loading requirements to prevent needless imports. not documented. might not need to be, as it just removes formerly legal
#0069 adds byte string and character literals (eg
#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.
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:
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. :-)
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!
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—
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!
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.
@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.
Also, now that the reference is extracted, it would be good to have this moved over to its repo....... we should talk about how to best do that.…
On Fri, Mar 10, 2017 at 10:36 AM, Chris Krycho ***@***.***> wrote: Don't worry: I haven't forgotten.