Initial draft of doctest-name RFC

This RFC proposes the ability to annotate documentation test code blocks
with metadata of the form `name=NAME`. The given name will be used to
identify the documentation test when it is run by the test runner, in
addition to the current information of test binary, module, and line
number.

For example, this documention test:

    ```name=arithmetic
    assert_eq!(2 + 2, 4);
    ```

Assuming that it is in crate `foo`, in file `src/lib.rs`, in module
`bar`, on line 37, will produce this output when run:

       Doc-tests foo

    running 1 test
    test src/lib.rs - bar::arithmetic (line 37) ... ok

    test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Author: casey

text/0000-doctest-name.md

@@ -0,0 +1,142 @@
+- Feature Name: doctest-name
+- Start Date: 2010-10-07
+- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000)
+- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000)
+
+# Summary
+[summary]: #summary
+
+Allow giving documentation tests names for identification in teest runner
+output by including `name=NAME` in doctest code block info strings.
+
+# Motivation
+[motivation]: #motivation
+
+When doctests run, the test runner prints the name of the module that contains
+them and the line number that they start on. If a module contains many
+doctests, it is hard to identify which doctest is which in the test runner
+output by line number alone.
+
+By giving users the option to give names to doctests, identifying individual
+doctests in test runner output will be easier.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+Doctests are written as fenced markdown code blocks that start and end
+with lines containing three backticks.
+
+The first set of backticks may be followed by an info string. For example, to
+tell the Rust compiler to ignore the doctest:
+
+````rust
+
+// This doctest won't run.
+```ignore
+assert_eq!(2 + 2, 4);
+```
+
+````
+
+Normally, doctests do not have names, and when run, the test runner will
+identify them by their test binary, module name, and line number:
+
+```
+   Doc-tests foo
+
+running 1 test
+test src/lib.rs - bar (line 37) ... ok
+
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
+```
+
+If you'd like to have the test runner print a more informative name, perhaps
+because there are many doctests in a single file, you can put `name=NAME`,
+where `NAME` is the name the test should have, in the doctest's info string.
+`NAME` should be a valid Rust identifer.
+
+
+````rust
+
+```name=arithmetic
+assert_eq!(2 + 2, 4);
+```
+
+````
+
+```
+   Doc-tests foo
+
+running 1 test
+test src/lib.rs - bar::arithmetic (line 37) ... ok
+
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
+```
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+The set of valid words that may appear in code block info strings is extended
+to include patterns of the form `name=IDENT`.
+
+This `IDENT` will be the name of the documentation test generated by the code
+block.
+
+When the test runner runs the documentation test, the test will be identified
+by this name, in addition to the test binary, module, and line number.
+
+Multiple `name=IDENT` words may not appear in a single code block's info
+string.
+
+`name=IDENT` may be combined with existing annotations like `rust` or
+`should_panic` by separating the annotations with commas:
+
+````
+
+```rust,name=foo
+assert!(true)
+```
+
+````
+
+The ability to include multiple comma-separated annotations is an existing
+feature.
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+- Adds complexity to code block parsing.
+
+- Requires parsing multi-word info strings, which are standard markdown, but
+  which does increase the complexity of the markdown parser.
+
+# Rationale and alternatives
+[rationale-and-alternatives]: #rationale-and-alternatives
+
+This design seems like the simplest design possible, although viable
+alternatives may have been overlooked.
+
+A previous version of this RFC included the additional restrictions that labels
+must be valid rust identifiers, and that labels must be unique within the same
+module. These restrictions were intended to allow the machinery that generates
+doctest tests to use the labels as the generated doctest function names. If
+this simplifies or improves the generated doctest functions, these restrictions
+might be desirable.
+
+The impact of adopting this RFC is minimal. Doctests test output will remain a
+little hard to make sense of.
+
+# Prior art
+[prior-art]: #prior-art
+
+None.
+
+# Unresolved questions
+[unresolved-questions]: #unresolved-questions
+
+None.
+
+# Future possibilities
+[future-possibilities]: #future-possibilities
+
+None.