Review changes and associated docs updates

Author: gspencergoog

lib/src/dartdoc_options.dart

@@ -56,6 +56,9 @@ class DartdocFileMissing extends DartdocOptionError {
   DartdocFileMissing(String details) : super(details);
 }
 
+/// Defines the attributes of a category in the options file, corresponding to
+/// the 'categories' keyword in the options file, and populated by the
+/// [CategoryConfiguration] class.
 class CategoryDefinition {
   /// Internal name of the category.
   final String name;
@@ -73,6 +76,8 @@ class CategoryDefinition {
   String get displayName => _displayName ?? name;
 }
 
+/// A configuration class that can interpret category definitions from a YAML
+/// map.
 class CategoryConfiguration {
   /// A map of [CategoryDefinition.name] to [CategoryDefinition] objects.
   final Map<String, CategoryDefinition> categoryDefinitions;
@@ -110,8 +115,16 @@ class CategoryConfiguration {
   }
 }
 
+/// Defines the attributes of a tool in the options file, corresponding to
+/// the 'tools' keyword in the options file, and populated by the
+/// [ToolConfiguration] class.
 class ToolDefinition {
+  /// A list containing the command and options to be run for this tool. The
+  /// first argument in the command is the tool executable. Must not be an empty
+  /// list, or be null.
   final List<String> command;
+
+  /// A description of the defined tool. Must not be null.
   final String description;
 
   ToolDefinition(this.command, this.description)
@@ -123,6 +136,7 @@ class ToolDefinition {
   String toString() => '$runtimeType: "${command.join(' ')}" ($description)';
 }
 
+/// A configuration class that can interpret [ToolDefinition]s from a YAML map.
 class ToolConfiguration {
   final Map<String, ToolDefinition> tools;
 

test/model_test.dart

@@ -92,12 +92,21 @@ void main() {
       packageGraph.allLocalModelElements.forEach((m) => m.documentation);
     });
     test("can invoke a tool", () {
-      expect(invokeTool.documentation, contains('## `Yes it is!`'));
+      expect(
+          invokeTool.documentation,
+          contains(
+              '''Args: [--file=<INPUT_FILE>, --special= |\\[]!@#\\"\'\$%^&*()_+]'''));
+      expect(invokeTool.documentation, contains('## `Yes it is a [Dog]!`'));
+    });
+    test("can invoke a tool and add a reference link", () {
+      expect(invokeTool.documentation,
+          contains('Yes it is a [Dog]! Is not a [ToolUser].'));
     });
     test(r"can invoke a tool with no $INPUT or args", () {
       expect(invokeToolNoInput.documentation, contains('Args: []'));
       expect(invokeToolNoInput.documentation,
           isNot(contains('This text should not appear in the output')));
+      expect(invokeToolNoInput.documentation, isNot(contains('[Dog]')));
     });
   });
 

testing/test_package/bin/drill.dart

@@ -4,6 +4,9 @@
 
 // Used by tests as an "external tool". Has no other useful purpose.
 
+// This is a sample "tool" used to test external tool integration into dartdoc.
+// It has no practical purpose other than that.
+
 import 'dart:io';
 import 'package:args/args.dart';
 
@@ -32,6 +35,7 @@ void main(List<String> argList) {
       List<String> lines = file.readAsLinesSync();
       for (String line in lines) {
         print('## `${line}`');
+        print('\n$line Is not a [ToolUser].\n');
       }
     } else {
       exit(1);

testing/test_package/lib/example.dart

@@ -586,15 +586,15 @@ abstract class ToolUser {
   /// Invokes a tool.
   ///
   /// {@tool drill --file="$INPUT" --special=" |\[]!@#\"'$%^&*()_+"}
-  /// Yes it is!
+  /// Yes it is a [Dog]!
   /// Ok, fine it isn't.
   /// {@end-tool}
   void invokeTool();
 
   /// Invokes a tool without the $INPUT token or args.
   ///
   /// {@tool drill}
-  /// This text should not appear in the output.
+  /// This text should not appear in the output, even if it references [Dog].
   /// {@end-tool}
   void invokeToolNoInput();
-}
+}

testing/test_package_docs/ex/ToolUser/invokeTool.html

@@ -73,8 +73,10 @@ <h1>invokeTool method</h1>
     <section class="desc markdown">
       <p>Invokes a tool.</p>
 <p>Args: <code>--file=&lt;INPUT_FILE&gt;, --special= |[</code>!@#"'$%^&amp;*()_+]</p>
-<h2 id="yes-it-is"><code>Yes it is!</code></h2>
+<h2 id="yes-it-is-a-dog"><code>Yes it is a [Dog]!</code></h2>
+<p>Yes it is a <a href="ex/Dog-class.html">Dog</a>! Is not a <a href="ex/ToolUser-class.html">ToolUser</a>.</p>
 <h2 id="ok-fine-it-isnt"><code>Ok, fine it isn't.</code></h2>
+<p>Ok, fine it isn't. Is not a <a href="ex/ToolUser-class.html">ToolUser</a>.</p>
     </section>
 
 

testing/test_package_docs_dev/ex/ToolUser/invokeTool.html

@@ -73,8 +73,10 @@ <h1>invokeTool method</h1>
     <section class="desc markdown">
       <p>Invokes a tool.</p>
 <p>Args: <code>--file=&lt;INPUT_FILE&gt;, --special= |[</code>!@#"'$%^&amp;*()_+]</p>
-<h2 id="yes-it-is"><code>Yes it is!</code></h2>
+<h2 id="yes-it-is-a-dog"><code>Yes it is a [Dog]!</code></h2>
+<p>Yes it is a <a href="ex/Dog-class.html">Dog</a>! Is not a <a href="ex/ToolUser-class.html">ToolUser</a>.</p>
 <h2 id="ok-fine-it-isnt"><code>Ok, fine it isn't.</code></h2>
+<p>Ok, fine it isn't. Is not a <a href="ex/ToolUser-class.html">ToolUser</a>.</p>
     </section>