The Standard Library Documentation Checklist
Closed this issue · 27 comments
I've been doing work on random parts of the standard library, but it's time to get systematic.
Here's a list of all of the top-level modules in std, with separate tracking issues for each part. Documentation is never done, but I'd at least like to ensure that every module is seen at least once.
PRs will be sent for consistency, more examples, better explanations, all the usual stuff. But here's how we can track progress.
One specific area where we can do much better is linking of types to their docs in text explanations.
- home page #29330
- array #29331
- bool #29332
- char #29333
- floats #29334
- integers #29335
- raw pointers #29336
- slices #29337
- str #29338
- tuples #29339
- any #29340
- borrow #29342
- boxed #29343
- cell #29344
- char #29345
- clone #29346
- cmp #29347
- collections #29348
- convert #29349
- default #29350
- env #29351
- error #29352
- std::float #29353
- ffi #29354
- fmt #29355
- fs #29356
- hash #29357
- std::integer #29358
- io #29359
- iter #29360
- marker #29361
- mem #29362
- net #29363
- num #29364
- ops #29365
- option #29366
- os #29367
- prelude #29369
- process #29370
- ptr #29371
- rc #29372
- result #29373
- std::slice #29374
- std::str #29375
- string #29376
- sync #29377
- thread #29378
- time #29379
- vec #29380
- macros #29381
- std::char #29428
One specific area where we can do much better is linking of types to their docs in text explanations.
Regarding this, is there any hope of extending Markdown with a way to reference Rust items, so you don't have to rely on knowing the URL structure?
I'm not aware of CommonMark having extension capabilities, but yeah, let's just say that there's nothing close enough on the horizon to actually use.
let's just say that there's nothing close enough on the horizon to actually use.
But why not add a thin layer in rustdoc which could translate links of the form, say, rustdoc://std::collections::BinaryHeap into /std/collections/struct.BinaryHeap.html before passing it to the markdown parser?
@cristicbz such would be nice
yeah
Replacing hoedown with https://github.com/google/pulldown-cmark should make these translations trivial because it exposes a token-stream-like interface that can be mapped over.
Has anyone started working on replacing with pulldown-cmark?
I was looking at librustdoc source, didn't get the flow of parsing... I'll take a better look later -- an interaction diagram would have helped a lot.
(Interaction diagrams of building the compiler would also be a nice-to-have -- could replace nitty-gritty.)
I don't believe so, no. Rustdoc in general needs a ton of help.
The flow of parsing is bananas and involves recording events using thread-local statics. I believe @alexcrichton wants to address the problem of Rust depending on external crates in tandem with this project.
I'm going to take a look as soon as I can.
I toggled the added docs. All up to date now.
Has anyone started working on replacing [hoedown] with pulldown-cmark?
This is almost done now, except for rendering of books. Once the buildsystem is moved to Cargo-based, I think we should also think about supporting custom links.
@critiqjo oh wow! That's awesome
@steveklabnik Looks like io, num, std::slice, and vec are closed and can be checked off.
Suggestion: Turn this into a Project? (Might help in gaining visibility, or just to test if the workflow helps?)
@critiqjo I like that idea! Is anybody against it? I would put one up but it seems that project creation is restricted.
I think I went over every items. Once I have time, I'll try to check if I missed any.
We haven't, as a matter of project policy, decided if we're using projects, and for what.
We should talk about it at the next docs meeting.
Update: I'm going to go through all of the ones that are still open today and elaborate on exactly what they need to have done to be considered closed.
Update:
envis checked off, but probably shouldn't be, as #29351 is open- the issues for
hash,net, andstd::strhave been closed, so these can be checked off pathisn't listed currently (#29368)asciiisn't listed currently either; #29341 is still open, but can be closed, so this should probably be checked off as welloptionwas already checked off somehow, but the issue is still open; as forasciithough, it has been addressed and can be closed as far as I can tell
Unchecked env.
Checked hash, net, and std::str.
path and ascii still need to be added.
@steveklabnik update checklist please:
convert, done
env, done
Updated.
I think this issue has served its use. There's only a few things left, and we can track them in their own issues.
Thank you to everyone who pitched in and made the standard library docs better over the last three years! ❤️