Topics for the "rustdoc" chapter

[japaric]

• Which comment styles /// get translated to docs
• How to use the rustdoc command
• #[doc] attributes: inline, no_inline, hidden
• Playpen integration
• Do we have "[doctests(https://docs.python.org/2/library/doctest.html)]"? i.e. examples in the docs that get tested to match some expected output
• The std docs have been generated using rustdoc!

[steveklabnik]

I'd be happy to mentor anyone who wants to work on this!

[frewsxcv]

somewhat relevant: we have a rustdoc resource we can link to now: https://doc.rust-lang.org/stable/rustdoc/

[jsjoeio]

@steveklabnik it's been a few years 😂 Are you still willing to mentor someone on this?

I'd be up for giving this a shot.

[steveklabnik]

Hi @jsjoeio !

So, I am in the sense that I can help you with the mechanics of how to contribute, etc. But I haven't worked on RBE for a long time, so I am not entirely sure that the list above makes sense. That is, I don't know what stuff has landed and what stuff hasn't, if the list above is still relevant, etc.

Is there something specific that made you pick this issue? If so, we can dive into that and I can help you out for sure!

[jsjoeio]

Thanks for the speedy reply @steveklabnik!

That is, I don't know what stuff has landed and what stuff hasn't, if the list above is still relevant, etc.

Good to know. That might be a good first step then - identifying what's landed and what hasn't.

Is there something specific that made you pick this issue?

Nope! I chose it because

• it had the label "E-mentor"
• no one else had grabbed it
• docs seemed like a good entry point into Rust OSS

Next Steps

I think what I'll do then is get started on this. Here's what I'm thinking:

• familiarize myself with RBE
• identify what's landed and what hasn't

Afterwards, I'll share thoughts and questions here and we can go from there. How does that sound?

[jsjoeio]

Audit

Here's a summary of what's landed and what hasn't:

✅ Which comment styles /// get translated to docs

This is covered in the "Documentation" topic of RBE. I didn't find anything worth adding.

✅ How to use the rustdoc command

rustdoc mentioned a few times here on the "Documentation" topic of the "Meta" chapter.

It links to the Rustdoc book, so it probably doesn't make sense to add more to RBE.

❌ #[doc] attributes: inline, no_inline, hidden

There is no mention of this in RBE, but it is mentioned in the Rustdoc book.

❌ Playpen integration

Absolutely no mention of this. By integration, what is meant? Does it mean this, where you see a playground embed within the docs? I assume it's referring to the ability to do this:

Either way, no mention. Let me know if you have suggestions to include this. I would probably add it as it's own topic under "Meta"

✅ Do we have

"[doctests(https://docs.python.org/2/library/doctest.html)]"? i.e.
examples in the docs that get tested to match some expected output

Based on my understanding of this, I believe this is covered here in "Documentation testing".

❌ The std docs have been generated using rustdoc!

I didn't see this mentioned anywhere. Maybe we could add a short sentence to the "Documentation" topic mentioning this?

Suggested Fixes

• Fix spelling/style of rustdoc on the "Documentation" page (i.e. Rustdoc vs rustdoc vs rustdoc -> make it consistent rustdoc) - fix: make spelling/style of rustdoc consistent #1321
• Add examples of #[doc] attributes to the "Documentation" topic in RBE - feat: add doc attributes section to documentation #1323
• Create "Playpen" topic and add to "Meta" - feat: add playpen topic #1324
• Add sentence about std docs to "Documentation" - feat: add sentence about rustdoc & std library #1322

[steveklabnik]

Absolutely no mention of this. By integration, what is meant? Does it mean this, where you see a playground embed within the docs? I assume it's referring to the ability to do this:

I believe this is accurate, yes!

I didn't see this mentioned anywhere. Maybe we could add a short sentence to the "Documentation" topic mentioning this?

Sounds good to me :)

[jsjoeio]

PRs opened for all! Now time to wait and hear for feedback.

After changes are made and PRs are merged, this will be done 😎 🏄🏼‍♂️

[jsjoeio]

As of this morning, all my PRs have been merged in 🎉!

@steveklabnik feel free to close!

[marioidival]

@jsjoeio good