Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.
Sign upDocument all features #9
Comments
This was referenced Mar 11, 2017
steveklabnik
added
Bug
Help Wanted
labels
Mar 13, 2017
This comment has been minimized.
This comment has been minimized.
mattico
commented
Mar 16, 2017
|
Also needs documenting: |
frewsxcv
referenced this issue
Mar 25, 2017
Closed
'Compiler Features' section overlaps with Unstable Book #27
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
Would it be useful to have a link in the nightly lang reference to this issue? |
This comment has been minimized.
This comment has been minimized.
|
@mrhota that's a great idea! |
This comment has been minimized.
This comment has been minimized.
Eh2406
commented
Mar 29, 2017
•
|
Note for anyone viewing this page there is a long list of RFC that still need the documentation status evaluated. I am happy to merge changes from forks of the gist. |
This comment has been minimized.
This comment has been minimized.
|
Even simpler, let's have interested people fork my new copy of the original (for which a thousand thanks, @Eh2406!) and I can more easily merge them and track them myself! |
This comment has been minimized.
This comment has been minimized.
chriskrycho
referenced this issue
Mar 29, 2017
Open
Canonical Rust grammar distinct from parser (tracking issue for RFC #1331) #30942
This comment has been minimized.
This comment has been minimized.
|
Could you add something in the description for those of us who want to help but don't know what you want us to do? Right now all I see is a big list of stuff but I'm not sure what you want us to help with and how exactly you want us to go about it. This is a very monolithic issue and it's hard to know what to do if you haven't helped with this kind of thing before. |
This comment has been minimized.
This comment has been minimized.
|
Absolutely! I'll add that later this afternoon.
|
This comment has been minimized.
This comment has been minimized.
|
Note: This is integrated into the body of the issue as well; just adding it here so everyone who's watching the issue sees it via notification! "How Can I Help?"For right now, since you can't submit updates to the issue directly, there are two major ways you can help:
|
mrhota
added a commit
to mrhota/reference
that referenced
this issue
Apr 3, 2017
QuietMisdreavus
referenced this issue
Apr 14, 2017
Merged
document default object lifetime bounds #40
This comment has been minimized.
This comment has been minimized.
|
@chriskrycho You can tick C.1 (or convert all the sub-bullets to boxes and tick them all!). See #35. |
This comment has been minimized.
This comment has been minimized.
|
@chriskrycho I opened a pull request for #558. |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
#41 has been merged (thanks @steveklabnik), you can tick "#558: require parentheses for chained comparisons – the requirement is not documented in the reference". |
This was referenced Apr 18, 2017
This comment has been minimized.
This comment has been minimized.
|
@chriskrycho I think that I've got all of the simple RFCs done in the gist now, and have categories and links for just about everything else to help anyone wanting to check the more complicated RFCs more carefully. |
This comment has been minimized.
This comment has been minimized.
|
Excellent! I'll have a nice block of time off and will review those quickly and hit some of the more complicated ones starting next week!
|
This comment has been minimized.
This comment has been minimized.
|
Thanks @brson @mrhota @dhardy @sanmai-NL! My vacation was far more productive than I planned in non-Rust categories, in that we bought a house; but accordingly less productive here. Current goal is to spend at least one hour every week working on this going forward. Here's hoping. |
This comment has been minimized.
This comment has been minimized.
lukaramu
commented
Aug 12, 2017
|
Looks like the tracking list hasn't been updated in a while, it's missing the following RFCs:
|
This comment has been minimized.
This comment has been minimized.
|
Thank you very much @lukaramu! And status update for everyone else: I ended up in a surprising spot as maintainer of ember-cli-typescript and that ate my summer. I'm close to getting that stable and coming back to this. |
Havvy
added
Enhancement
Tracking Issue
labels
Sep 24, 2017
This comment has been minimized.
This comment has been minimized.
|
I'm confused both as to what the statuses are (what do stabilized and reviewed mean?) and where the current work is. |
This comment has been minimized.
This comment has been minimized.
|
Totally fair! Stabilized means the RFC feature has been merged to stable Rust. Reviewed means I or someone else had looked over the documentation and confirmed whether an RFC feature is documented or not.
Status is basically the above comments and the Gists linked in them. I am actually planning on taking some time on Jan. 1 to write up some comments on all of this and expect to knock out the rest of the review triage in the next month or so, which should make it way easier for people to just document those currently-undocumented RFC features.
|
This comment has been minimized.
This comment has been minimized.
|
Any progress? I'd like to start trying to submit PRs for easier RFCs. |
This comment has been minimized.
This comment has been minimized.
|
No, and sorry for the delay. I will pick this work up Tuesday afternoon!
|
This comment has been minimized.
This comment has been minimized.
|
Is there anything I can do to help you out at this point? |
This comment has been minimized.
This comment has been minimized.
|
Can you unpack my house?
|
This comment has been minimized.
This comment has been minimized.
|
Unfortunately I'm on the wrong continent at the moment! I'm sorry to hear about your family, I hope things go well. I look forward to getting things sorted. When you do, would it perhaps make sense to file a bug for each RFC? |
This comment has been minimized.
This comment has been minimized.
Eh2406
commented
Jan 21, 2018
|
People can at any time fined a RFC that is not documented and make a pr to improve the documentation. That is not dependent on this organisation getting updated. |
This comment has been minimized.
This comment has been minimized.
|
@alercah just a thought: could you provide a snapshot or summary of where this issue currently is, accounting for all comments and stuff? That would probably take some pressure off @chriskrycho since he could then just copy your snapshot/summary into the OP when he gets a free moment. Come to think of it, if you want to work on it together, I'm going to get on IRC in the #rust-docs channel. I recently wanted to summarize this issue myself, and I'm feeling inspired now. |
This comment has been minimized.
This comment has been minimized.
|
ok, @chriskrycho, I'm updating your gist in my fork here. Hopefully it'll be easy to incorporate the updates into your copy. I'm also incorporating changes from other forks of your gist, so you'll just be able to copy over changes from mine. |
This comment has been minimized.
This comment has been minimized.
|
Excellent!
|
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
I've now put all the "needs review" RFCs in, except for ones which I poked at and they completely obviously didn't (either not stable or not related to the language). |
This comment has been minimized.
This comment has been minimized.
|
Thank you *very* much!
|
This comment has been minimized.
This comment has been minimized.
|
I removed all the unstable RFCs from the Needs Review column, since they'll get docs as part of their work. A few I moved into the Awaiting column, and a few I closed as unrelated since they were obviously e.g. library-only PRs. |
This comment has been minimized.
This comment has been minimized.
|
GitHub needs a "You're my hero!" response-moji. |
This comment has been minimized.
This comment has been minimized.
|
I've gone through and added all the ones marked as needing documentation, up to but not including the "Macros" section on the Gist. Only a few left. |
This comment has been minimized.
This comment has been minimized.
|
I've opened a bigger issue for macros, and linked the relevant RFCs, since macro documentation is sorely lacking. The remaining ones in "It's complicated..." are either library-only or documented to the extent that they need to be in the reference, so no need to do further work. I would say the Gist is now fully ported into the issue tracker & project page. I propose closing this issue. |
This comment has been minimized.
This comment has been minimized.
|
|
This comment has been minimized.
This comment has been minimized.
|
This is awesome! I agree, looks like you've gotten everything. Let's close. |
chriskrycho commentedMar 11, 2017
•
edited by Havvy
Overview
Tracking issue for RFC #1636. Let's make the reference a reliable resource for all Rustaceans!🎉 This might seem intimidating, but the reality is that if we just chip away at it together, we'll be done in no time!
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.)
Status: Last updated May 13, 2017, now processing a copy of @Eh2406's wonderful gist based on @matthewjasper's fork here.
"How Can I Help?"
For right now, since you can't submit updates to the issue directly, there are two major ways you can help:
Write documentation. For the RFCs already triaged and filed under the major section C. Documentation Needed and specifically the subsection 2. Write reference material for undocumented, implemented, stabilized RFC features below, you can open a pull request and reference this issue in its description. I'll keep an eye out for inbound links here and add those links to the relevant items, and once they're merged, we'll mark that item as done.
Triage issues. Work the gist where I'm tracking the triaged-state, specifically looking at the Not Reviewed at All and Stabilized, Not Reviewed sections and evaluating whether they're documented or not. You can fork the gist and I will keep an eye out, checking roughly daily, for any changes to merge back into that document. (Do take a look at what others may have forked it so you don't duplicate work needlessly!) I'll then pull those over into this master issue.
When working through those, if you determine that they're already documented, please leave a note (and link!) on your copy of the gist as to where so I can link it in this document. That dramatically decreases the time it takes me to confirm it—I double-check all of these.
A. 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: 115/301
RFCs unreviewed
B. 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."
C. 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.)
plugin-registrarAPIrepr_align– implementation is in-progress, not yet landed on nightlyloop_break_value0.2. Track accepted, not-yet-implemented or implementation-in-progress, undocumented RFCs
These will eventually require documentation, but as they aren't even (fully) implemented yet, there is no urgency here.
{Vec,String}::splice– tracking issuemacro_rules!– tracking issuemacro_rules– tracking issueshared_from_slice– tracking issueManuallyDropto core – tracking issueeprint!andeprintln!– tracking issue1. 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 (once finished, this list should do just fine, perhaps with some massaging for descriptiveness)
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-facade&mutpatterns – symmetry of pattern syntax not documentedcrt_linkunaligned_access3. Update out-of-date/incomplete sections of the reference
List of language items
Coherence
Orphan rules (#5)
Lifetime elision
D. Documentation not needed
0. 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 Compilationfmt::Showandfmt::Stringtofmt::Debugandfmt::Displayrespectively, along with where to implement them; documented in the entire standard library as well as specifically atstd::fmt::Debugandstd::fmt::Displaystr::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 instd1. Retired
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.2. 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_assert3. Parser-specific
Some changes are specific to the parsing (though they affect the language). These should be documented not in the reference but in the language grammar.
4. Process and conventions
Io:Error, notIo::IoError)unwraprustcbugfix best practices5. Non-language features
Note: I've just copied over the original issue as it was—wholesale. Note that some of the links here referencing things as "already documented" will degrade given the new structure of the book.