Document all features in the reference #38643
Comments
|
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. |
steveklabnik
added
A-docs
E-help-wanted
|
Having a list to work off of will be a great start! |
|
Edit: moved all of this to the main issue. |
|
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. |
|
#0019 is… wow. Old, and moving slowly but steadily. Also going to require some work to figure out what the documentation status is! |
|
long live #20137 |
|
It's prior art! |
|
#0034 |
|
@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! |
|
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. |
|
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). |
|
I am skipping around to find ones that I can tell about. |
|
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!) |
|
Wow @Eh2406 thanks for the research. |
|
@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).
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. |
|
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 #0059 - #0063 - tightens the module loading requirements to prevent needless imports. not documented. might not need to be, as it just removes formerly legal #0068 #0069 adds byte string and character literals (eg 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. |
|
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—
👍 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! |
Possibly, send one in for whatever you think is best and we can discuss it in-PR. |
|
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 |
Already Documented1054-str-words.md 1057-io-error-sync.md 1058-slice-tail-redesign.md 1066-safe-mem-forget.md 1102-rename-connect-to-join.md 1119-result-expect.md 1123-str-split-at.md Implemented, Unstable1131-likely-intrinsic.md Process RFCs1068-rust-governance.md 1105-api-evolution.md 1122-language-semver.md Removals |
|
Awesome work, @Eh2406 and @alanstoate! I'll see about integrating those into the primary post over the weekend. |
|
ping? |
|
I'll have some time again this weekend. The last two weeks I've been in class for a week-long intensive and then playing catchup after it.
|
|
https://gist.github.com/Eh2406/57e9b7d4d2be1dd11eb400de9c65ec8f 37 not yet looked at! :-) |
|
https://gist.github.com/Eh2406/57e9b7d4d2be1dd11eb400de9c65ec8f All are looked at! |
|
Amazing work! I'll try to integrate these this weekend!
|
|
Some features are added without any rfc process, how should these cases be handled? |
|
@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. |
|
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. |
|
That would be grand! The last few weeks I've had surprising things come up on weekends. I am still going to get to this.
|
|
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! |
|
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. |
|
You, sir, are a hero among Rustaceans. Truly.
|
|
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
removed
the
A-docs
|
@chriskrycho ping? |
|
Don't worry: I haven't forgotten. 😄 It has just been a nutty month including the last class of my masters degree. I will actually have a few hours blocked out this weekend, and several every week until it is done from here on out.
|
|
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. 😄 It has just been a nutty month
including the last class of my masters degree. I will actually have a few
hours blocked out this weekend, and several every week until it is done
from here on out.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#38643 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AABsiqr0Qm0qu7Q8DfSrVpEFHTzbGH-wks5rkW3mgaJpZM4LWl84>
.
|
|
Should be pretty straightforward at present. I'll copy the issue over later and then just keep working for the gist. Sadly, a lot of the section links no longer work and will need to be updated (the only real loss from the move).
|
|
Closing in favor of the corresponding issue in the new repository. |
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:
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
RFCs unreviewed
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.)
loop_break_value0.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.
Create the appendix
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-facadecrt_linkunaligned_access3. Update out-of-date/incomplete sections of the reference
List of language items
Coherence
Orphan rules
Lifetime elision
Documentation not needed
Already documented
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 Compilationstr::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 instdRetired
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.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_assertProcess and conventions
rustcbugfix best practicesThe text was updated successfully, but these errors were encountered: