The Rustdoc book #42378

steveklabnik · 2017-06-02T12:59:40Z

A work-in-progress start for docs for rustdoc.

This doesn't actually generate the docs yet; I wanted to open this PR to get feedback on this approach, the chapters headings themselves, and to see if anyone wanted to help fill in the ones that aren't done yet.

Start of #42322.

/cc @rust-lang/dev-tools @rust-lang/docs

rust-highfive · 2017-06-02T12:59:51Z

r? @frewsxcv

(rust_highfive has picked a reviewer for you, use r? to override)

killercup

Good start. Left a few comments.

FTR, I'd really like the passes chapter to contain the needed args to render all items, even private ones. (I'm pretty sure cargo doc -- --no-defaults --passes collapse-docs --passes unindent-comments worked once)

killercup · 2017-06-02T13:53:13Z

src/doc/rustdoc/src/command-line-arguments.md

+like this:
+
+```text
+rustdoc 1.y.0 (hash date)


hash date? Never heard of her. (I wouldn't try to make the output generic but give concrete, current outputs. People can easily see the pattern themselves and I'm not sure we want to guarantee this will always look like this.)

killercup · 2017-06-02T13:54:28Z

src/doc/rustdoc/src/command-line-arguments.md

+For example, with `--version`:
+
+```text
+$ rustdoc --version -v


That looks weird. Either -v -V or --verbose --version

killercup · 2017-06-02T13:56:54Z

src/doc/rustdoc/src/command-line-arguments.md

@@ -0,0 +1,358 @@
+# Command-line arguments
+
+Here's the list of arguments you can pass to `rustdoc`:


Maybe add a warning that these do not work with cargo doc

Nope:

$cargo doc --passes strip-priv-imports error: Unknown flag: '--passes …

I think it was once possible to do cargo doc -- args… but with latest stable:

$ cargo doc -- --passes strip-priv-imports error: Invalid arguments.

Right, you'd have to use RUSTDOCFLAGS for this, much like RUSTFLAGS for arguments to rustc.

killercup · 2017-06-02T13:59:56Z

src/doc/rustdoc/src/what-is-rustdoc.md

+$ cargo doc
+```
+
+Internally, this calls out to `rustdoc` like this:


Internally*

* you can see this with cargo doc --verbose

steveklabnik · 2017-06-02T17:02:37Z

FTR, I'd really like the passes chapter to contain the needed args to render all items, even private ones. (I'm pretty sure cargo doc -- --no-defaults --passes collapse-docs --passes unindent-comments worked once)

Yup, agreed

frewsxcv

looking forward to this!

ignore my previous approval, that was an accident

frewsxcv · 2017-06-03T21:27:55Z

src/doc/rustdoc/src/command-line-arguments.md

+as the `.rs` file. `--crate-name` lets you override this assumption with
+whatever name you choose.
+
+stable(optmulti("L", "library-path", "directory to add to crate search path",


what's this doing?

also looks like these stable(...) things are used elsewhere in this file

i made this page by copy/pasting the source, and must have forgotten to remove these lines 😓

frewsxcv · 2017-06-03T21:32:49Z

src/doc/rustdoc/src/documentation-tests.md

@@ -0,0 +1,3 @@
+# Documentation tests
+
+Coming soon!


intending to ship this with the "Coming soon!" test?

I am happy shipping this at whatever point, this chapter should be easy to knock out though

frewsxcv · 2017-06-03T21:33:03Z

src/doc/rustdoc/src/what-is-rustdoc.md

@@ -0,0 +1,127 @@
+# What is rustdoc?
+
+The standard Rust distribution ships with a tool called `rustdoc`. It's job is


s/It's/Its

frewsxcv · 2017-06-03T21:34:52Z

src/doc/rustdoc/src/what-is-rustdoc.md

+Let's give it a try! Let's create a new project with Cargo:
+
+```bash
+$ cargo new docs -- lib


is this supposed to be --lib? isn't this the default for cargo new?

frewsxcv · 2017-06-03T21:36:30Z

src/doc/rustdoc/src/what-is-rustdoc.md

+We'll have some generated documentation. Open up `doc/docs/index.html` and
+check it out! It should show a link to the `foo` function's page, which
+is located at `doc/docs/fn.foo.html`. On that page, you'll see the "foo is
+a function" we put inside the documentation comment in our crate.


could also maybe rustdoc --open here, but not mandatory by any means

matthewjasper · 2017-06-03T21:39:20Z

src/doc/rustdoc/src/what-is-rustdoc.md

+
+```rust
+/// foo is a function
+fn foo() {}


Is this supposed to be pub fn?

steveklabnik · 2017-06-05T17:09:39Z

I've pushed up a commit that should address all rustdoc feedback so far.

steveklabnik · 2017-06-05T17:11:37Z

I think I would like to ship this as-is (that is, with these contents; I haven't made the build actually build the book yet), and fill out the rest later, but if everyone else wants me to finish it before merging, that's fine as well.

frewsxcv

r=me unless you have more changes

steveklabnik · 2017-06-07T14:54:11Z

@bors: r=frewsxcv

nope; at least not for now.

bors · 2017-06-07T14:54:12Z

📌 Commit 9331f04 has been approved by frewsxcv

bors · 2017-06-07T15:16:53Z

⌛ Testing commit 9331f04 with merge f062832...

The Rustdoc book A work-in-progress start for docs for rustdoc. This doesn't actually generate the docs yet; I wanted to open this PR to get feedback on this approach, the chapters headings themselves, and to see if anyone wanted to help fill in the ones that aren't done yet. Start of #42322. /cc @rust-lang/dev-tools @rust-lang/docs

bors · 2017-06-07T18:12:05Z

☀️ Test successful - status-appveyor, status-travis
Approved by: frewsxcv
Pushing f062832 to master...

steveklabnik added 3 commits May 31, 2017 12:46

add a new mdbook for rustdoc

9eeb83c

wip

4ed3a15

Coming soon

fd2cbf9

rust-highfive assigned frewsxcv Jun 2, 2017

killercup reviewed Jun 2, 2017

View reviewed changes

shepmaster added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Jun 2, 2017

frewsxcv approved these changes Jun 3, 2017

View reviewed changes

frewsxcv suggested changes Jun 3, 2017

View reviewed changes

matthewjasper reviewed Jun 3, 2017

View reviewed changes

address review feedback

2f0dc04

fix tests

9331f04

frewsxcv approved these changes Jun 7, 2017

View reviewed changes

bors merged commit 9331f04 into rust-lang:master Jun 7, 2017

steveklabnik deleted the rustdoc-docs branch October 25, 2017 18:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

The Rustdoc book #42378

The Rustdoc book #42378

steveklabnik commented Jun 2, 2017 •

edited

Loading

rust-highfive commented Jun 2, 2017

killercup left a comment

killercup Jun 2, 2017 •

edited

Loading

killercup Jun 2, 2017

killercup Jun 2, 2017

steveklabnik Jun 5, 2017

killercup Jun 5, 2017

QuietMisdreavus Jun 5, 2017

killercup Jun 2, 2017

steveklabnik commented Jun 2, 2017

frewsxcv left a comment

frewsxcv Jun 3, 2017

frewsxcv Jun 3, 2017

steveklabnik Jun 5, 2017

frewsxcv Jun 3, 2017

steveklabnik Jun 5, 2017

frewsxcv Jun 3, 2017

frewsxcv Jun 3, 2017

frewsxcv Jun 3, 2017

matthewjasper Jun 3, 2017

steveklabnik Jun 5, 2017

steveklabnik commented Jun 5, 2017

steveklabnik commented Jun 5, 2017 •

edited

Loading

frewsxcv left a comment

steveklabnik commented Jun 7, 2017

bors commented Jun 7, 2017

bors commented Jun 7, 2017

bors commented Jun 7, 2017

		@@ -0,0 +1,358 @@
		# Command-line arguments

		Here's the list of arguments you can pass to `rustdoc`:

		@@ -0,0 +1,127 @@
		# What is rustdoc?

		The standard Rust distribution ships with a tool called `rustdoc`. It's job is

The Rustdoc book #42378

The Rustdoc book #42378

Conversation

steveklabnik commented Jun 2, 2017 • edited Loading

rust-highfive commented Jun 2, 2017

killercup left a comment

Choose a reason for hiding this comment

killercup Jun 2, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveklabnik commented Jun 2, 2017

frewsxcv left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveklabnik commented Jun 5, 2017

steveklabnik commented Jun 5, 2017 • edited Loading

frewsxcv left a comment

Choose a reason for hiding this comment

steveklabnik commented Jun 7, 2017

bors commented Jun 7, 2017

bors commented Jun 7, 2017

bors commented Jun 7, 2017

steveklabnik commented Jun 2, 2017 •

edited

Loading

killercup Jun 2, 2017 •

edited

Loading

steveklabnik commented Jun 5, 2017 •

edited

Loading