From 2665e44b875edd29fe86654493ca949612ee6a5d Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Mon, 5 Feb 2024 12:31:09 -0600
Subject: [PATCH] A few minor documentation updates (#3641)

---
 README.md               | 45 +++++++++++++++++++++++++----------------
 doc/directives.md       |  4 ++--
 lib/resources/readme.md | 18 +++++++++++++++--
 3 files changed, 46 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index db62b5ee0a..1dd28db41e 100644
--- a/README.md
+++ b/README.md
@@ -14,8 +14,12 @@ For issues/details related to the hosted Dart SDK API docs, see
 
 ## Installation
 
-The [`dart`](https://dart.dev/tools/dart-tool) tool,
-with the `dart doc` command, is part of the [Dart SDK](https://dart.dev/get-dart).
+The [`dart`][] tool, with the [`dart doc`][] command,
+is part of the [Dart SDK][].
+
+[`dart`]: https://dart.dev/tools/dart-tool
+[`dart doc`]: https://dart.dev/tools/dart-doc
+[Dart SDK]: https://dart.dev/get-dart
 
 ## Generating docs
 
@@ -39,26 +43,31 @@ Documented 1 public library in 17.9 seconds
 Success! Docs generated into <path to dartdoc>/doc/api
 ```
 
-By default, the documentation is generated to the `doc/api` directory as static
-HTML files.
+By default, the documentation is generated to the `doc/api` directory as
+static HTML files.
+
+To view the generated documentation, you must load them with an HTTP server.
+To learn more, follow the [Viewing docs](#viewing-docs) guide.
 
 Run `dart help doc` to see the available command-line options.
 
 ## Viewing docs
 
-You can view the generated docs directly from the file system, but if you want
-to use the search function, you must load them with an HTTP server.
+To enable navigation and search, the generated docs must be
+served with an HTTP server.
 
-An easy way to run an HTTP server locally is to use the `dhttpd` package. For
-example:
+An easy way to run an HTTP server locally is to use [`package:dhttpd`][].
+For example:
 
 ```
 $ dart pub global activate dhttpd
-$ dhttpd --path doc/api
+$ dart pub global run dhttpd --path doc/api
 ```
 
-Navigate to `http://localhost:8080` in your browser; the search function should
-now work.
+To then read the generated docs in your browser,
+open the link that `dhttpd` outputs, usually `http://localhost:8080`.
+
+[`package:dhttpd`]: https://pub.dev/packages/dhttpd
 
 ## Link structure
 
@@ -83,16 +92,18 @@ File names are _case-sensitive_.
 
 ## Writing docs
 
-Check out the
-[Effective Dart: Documentation guide](https://dart.dev/guides/language/effective-dart/documentation).
+To learn about writing documentation comments,
+check out the [Effective Dart: Documentation guide][].
 
 The guide covers formatting, linking, markup, and general best practices when
-authoring doc comments for Dart with `dartdoc`.
+authoring doc comments for Dart with `dart doc`.
+
+[Effective Dart: Documentation guide]: https://dart.dev/effective-dart/documentation
 
 ## Excluding from documentation
 
-`dart doc` will not generate documentation for a Dart element and its children that have the
-`@nodoc` tag in the documentation comment.
+`dart doc` will not generate documentation for a Dart element and
+its children that have the `@nodoc` tag in the documentation comment.
 
 ## Advanced features
 
@@ -501,7 +512,7 @@ Please see the [dartdoc license][].
 Generated docs include:
 
  * Highlight.js -
-   [LICENSE](https://github.com/isagalaev/highlight.js/blob/main/LICENSE)
+   [LICENSE](https://github.com/highlightjs/highlight.js/blob/main/LICENSE)
    * With `github.css` (c) Vasily Polovnyov <vast@whiteants.net>
 
 [GitHub Issue Tracker]: https://github.com/dart-lang/dartdoc/issues
diff --git a/doc/directives.md b/doc/directives.md
index 96c14309d2..59c31f9f20 100644
--- a/doc/directives.md
+++ b/doc/directives.md
@@ -11,8 +11,8 @@ The supported directives are listed below:
 
 ## `@nodoc` - Do not include documentation
 
-An element whose doc comment should not appear in the generated documenation can
-include the `@nodoc` directive.
+An element whose doc comment should not appear in the generated documentation
+can include the `@nodoc` directive.
 
 Note that the `@nodoc` directive does not have curly braces, like most of the
 other directives.
diff --git a/lib/resources/readme.md b/lib/resources/readme.md
index 357c11ca44..62216710a6 100644
--- a/lib/resources/readme.md
+++ b/lib/resources/readme.md
@@ -1,6 +1,20 @@
-# highlight.js
+# Dart documentation generator
 
-Generated from https://highlightjs.org/download/ on 2021-07-13
+This directory includes static sources used by the Dart documentation generator
+through the `dart doc` command.
+
+To learn more about generating and viewing the generated documentation,
+check out the [`dart doc` documentation][].
+
+[`dart doc` documentation]: https://dart.dev/tools/dart-doc
+
+## Third-party resources
+
+## highlight.js
+
+Generated from https://highlightjs.org/download/ on 2021-07-13.
+
+**License:** https://github.com/highlightjs/highlight.js/blob/main/LICENSE
 
 **Included languages:**