Enable smart punctuation

src/doc/rustdoc/src/how-to-write-documentation.md

@@ -101,7 +101,7 @@ what an item is, how it is used, and for what purpose it exists.
 Let's see an example coming from the [standard library] by taking a look at the
 [`std::env::args()`][env::args] function:
 
-``````text
+``````markdown
 Returns the arguments which this program was started with (normally passed
 via the command line).
 
@@ -135,7 +135,7 @@ for argument in env::args() {
 
 Everything before the first empty line will be reused to describe the component
 in searches and module overviews.  For example, the function `std::env::args()`
-above will be shown on the [`std::env`] module documentation.  It is good
+above will be shown on the [`std::env`] module documentation. It is good
 practice to keep the summary to one line: concise writing is a goal of good
 documentation.
 
@@ -153,9 +153,10 @@ and finally provides a code example.
 
 ## Markdown
 
-`rustdoc` uses the [CommonMark markdown specification]. You might be
-interested into taking a look at their website to see what's possible to do.
- - [commonmark quick reference]
+`rustdoc` uses the [CommonMark Markdown specification]. You might be
+interested in taking a look at their website to see what's possible:
+
+ - [CommonMark quick reference]
  - [current spec]
 
 In addition to the standard CommonMark syntax, `rustdoc` supports several
@@ -240,6 +241,21 @@ This will render as
 
 See the specification for the [task list extension] for more details.
 
+### Smart punctuation
+
+Some ASCII punctuation sequences will be automatically turned into fancy Unicode
+characters:
+
+| ASCII sequence | Unicode |
+|----------------|---------|
+| `--`           | –       |
+| `---`          | —       |
+| `...`          | …       |
+| `"`            | “ or ”, depending on context |
+| `'`            | ‘ or ’, depending on context |
+
+So, no need to manually enter those Unicode characters!
+
 [`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/
 [commonmark markdown specification]: https://commonmark.org/
 [commonmark quick reference]: https://commonmark.org/help/

src/librustdoc/html/markdown.rs

@@ -52,11 +52,12 @@ pub(crate) fn opts() -> Options {
         | Options::ENABLE_FOOTNOTES
         | Options::ENABLE_STRIKETHROUGH
         | Options::ENABLE_TASKLISTS
+        | Options::ENABLE_SMART_PUNCTUATION
 }
 
 /// A subset of [`opts()`] used for rendering summaries.
 pub(crate) fn summary_opts() -> Options {
-    Options::ENABLE_STRIKETHROUGH
+    Options::ENABLE_STRIKETHROUGH | Options::ENABLE_SMART_PUNCTUATION
 }
 
 /// When `to_string` is called, this struct will emit the HTML corresponding to

src/librustdoc/html/markdown/tests.rs

@@ -201,8 +201,8 @@ fn test_short_markdown_summary() {
     t("Hard-break  \nsummary", "Hard-break summary");
     t("hello [Rust] :)\n\n[Rust]: https://www.rust-lang.org", "hello Rust :)");
     t("hello [Rust](https://www.rust-lang.org \"Rust\") :)", "hello Rust :)");
-    t("code `let x = i32;` ...", "code <code>let x = i32;</code> ...");
-    t("type `Type<'static>` ...", "type <code>Type<'static></code> ...");
+    t("code `let x = i32;` ...", "code <code>let x = i32;</code> …");
+    t("type `Type<'static>` ...", "type <code>Type<'static></code> …");
     t("# top header", "top header");
     t("## header", "header");
     t("first paragraph\n\nsecond paragraph", "first paragraph");
@@ -227,8 +227,8 @@ fn test_plain_text_summary() {
     t("Hard-break  \nsummary", "Hard-break summary");
     t("hello [Rust] :)\n\n[Rust]: https://www.rust-lang.org", "hello Rust :)");
     t("hello [Rust](https://www.rust-lang.org \"Rust\") :)", "hello Rust :)");
-    t("code `let x = i32;` ...", "code `let x = i32;` ...");
-    t("type `Type<'static>` ...", "type `Type<'static>` ...");
+    t("code `let x = i32;` ...", "code `let x = i32;` …");
+    t("type `Type<'static>` ...", "type `Type<'static>` …");
     t("# top header", "top header");
     t("## header", "header");
     t("first paragraph\n\nsecond paragraph", "first paragraph");
@@ -250,6 +250,6 @@ fn test_markdown_html_escape() {
     }
 
     t("`Struct<'a, T>`", "<p><code>Struct&lt;'a, T&gt;</code></p>\n");
-    t("Struct<'a, T>", "<p>Struct&lt;'a, T&gt;</p>\n");
+    t("Struct<'a, T>", "<p>Struct&lt;’a, T&gt;</p>\n");
     t("Struct<br>", "<p>Struct&lt;br&gt;</p>\n");
 }

src/test/rustdoc/inline_cross/add-docs.rs

@@ -4,6 +4,6 @@ extern crate inner;
 
 
 // @has add_docs/struct.MyStruct.html
-// @has add_docs/struct.MyStruct.html "Doc comment from 'pub use', Doc comment from definition"
+// @has add_docs/struct.MyStruct.html "Doc comment from ‘pub use’, Doc comment from definition"
 /// Doc comment from 'pub use',
 pub use inner::MyStruct;

src/test/rustdoc/smart-punct.rs

@@ -0,0 +1,30 @@
+// ignore-tidy-linelength
+
+#![crate_name = "foo"]
+
+//! This is the "start" of the 'document'! How'd you know that "it's" the start?
+//!
+//! # Header with "smart punct'"
+//!
+//! [link with "smart punct'" -- yessiree!][]
+//!
+//! [link with "smart punct'" -- yessiree!]: https://www.rust-lang.org
+//!
+//! # Code should not be smart-punct'd
+//!
+//! `this inline code -- it shouldn't have "smart punct"`
+//!
+//! ```
+//! let x = "don't smart-punct me -- please!";
+//! ```
+//!
+//! ```text
+//! I say "don't smart-punct me -- please!"
+//! ```
+
+// @has "foo/index.html" "//p" "This is the “start” of the ‘document’! How’d you know that “it’s” the start?"
+// @has "foo/index.html" "//h1" "Header with “smart punct’”"
+// @has "foo/index.html" '//a[@href="https://www.rust-lang.org"]' "link with “smart punct’” – yessiree!"
+// @has "foo/index.html" '//code' "this inline code -- it shouldn't have \"smart punct\""
+// @has "foo/index.html" '//pre' "let x = \"don't smart-punct me -- please!\";"
+// @has "foo/index.html" '//pre' "I say \"don't smart-punct me -- please!\""