The Standard Library Documentation Checklist #29329

Open
steveklabnik opened this Issue Oct 26, 2015 · 21 comments

Projects

None yet

9 participants

@steveklabnik
Contributor
steveklabnik commented Oct 26, 2015 edited

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.

This was referenced Oct 26, 2015
@durka
Contributor
durka commented Oct 26, 2015

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?

@steveklabnik
Contributor

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.

@critiqjo
Contributor

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?

@tshepang
Contributor

@cristicbz such would be nice

@cristicbz
Contributor

@tshepang think you got the wrong guy

@tshepang
Contributor

yeah

@Gankro
Contributor
Gankro commented Oct 27, 2015

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.

@critiqjo
Contributor

@steveklabnik @Gankro ๐Ÿ‘

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.)

@steveklabnik
Contributor

I don't believe so, no. Rustdoc in general needs a ton of help.

@Gankro
Contributor
Gankro commented Oct 27, 2015

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.

@GuillaumeGomez
Member

I'm going to take a look as soon as I can.

@GuillaumeGomez
Member

I toggled the added docs. All up to date now.

@critiqjo
Contributor

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.

@steveklabnik
Contributor

@critiqjo oh wow! That's awesome

@steveklabnik steveklabnik added a commit to steveklabnik/rust that referenced this issue Jul 25, 2016
@steveklabnik steveklabnik Rollup merge of #34995 - GuillaumeGomez:dir_builder_doc, r=steveklabnik
Add DirBuilder doc examples

r? @steveklabnik

Part of #29329 and of #29356.
8c810ef
@bors bors added a commit that referenced this issue Jul 26, 2016
@bors bors Auto merge of #34995 - GuillaumeGomez:dir_builder_doc, r=steveklabnik
Add DirBuilder doc examples

r? @steveklabnik

Part of #29329 and of #29356.
1247fd9
@steveklabnik steveklabnik added a commit to steveklabnik/rust that referenced this issue Jul 26, 2016
@steveklabnik steveklabnik Rollup merge of #34995 - GuillaumeGomez:dir_builder_doc, r=steveklabnik
Add DirBuilder doc examples

r? @steveklabnik

Part of #29329 and of #29356.
ae05e62
@matthew-piziak
Contributor

@steveklabnik Looks like io, num, std::slice, and vec are closed and can be checked off.

@critiqjo
Contributor
critiqjo commented Dec 11, 2016 edited

Suggestion: Turn this into a Project? (Might help in gaining visibility, or just to test if the workflow helps?)

@matthew-piziak
Contributor

@critiqjo I like that idea! Is anybody against it? I would put one up but it seems that project creation is restricted.

@GuillaumeGomez
Member

I think I went over every items. Once I have time, I'll try to check if I missed any.

@steveklabnik
Contributor

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.

@frewsxcv
Member

Opened an issue for moving to pulldown-cmark: #38400

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