Add links for more details in API docs. (#1461)

jcollins-g · web-flow · commit e58142a6eb3b · 2017-06-20T12:24:37.000-07:00
* add ellipses with link to detailed docs

* Patch up tests

* dartfmt
diff --git a/lib/src/model.dart b/lib/src/model.dart
@@ -2289,6 +2289,15 @@ abstract class ModelElement extends Nameable
     return "(${p.toUri(sourceFileName)})";
   }
 
+  /// Returns a link to extended documentation, or the empty string if that
+  /// does not exist.
+  String get extendedDocLink {
+    if (hasExtendedDocumentation) {
+      return '<a href="${href}">[...]</a>';
+    }
+    return '';
+  }
+
   /// Returns the fully qualified name.
   ///
   /// For example: libraryName.className.methodName
@@ -2415,7 +2424,8 @@ abstract class ModelElement extends Nameable
   String get genericParameters => '';
 
   @override
-  String get oneLineDoc => _documentation.asOneLiner;
+  String get oneLineDoc =>
+      '${_documentation.asOneLiner}${extendedDocLink.isEmpty ? "" : " $extendedDocLink"}';
 
   ModelElement get overriddenElement => null;
 
diff --git a/test/model_test.dart b/test/model_test.dart
@@ -207,7 +207,7 @@ void main() {
       expect(
           fakeLibrary.oneLineDoc,
           equals(
-              'WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a>'));
+              'WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a> <a href="fake/fake-library.html">[...]</a>'));
     });
 
     test('has properties', () {
@@ -504,7 +504,7 @@ void main() {
       expect(
           add.oneLineDoc,
           equals(
-              'Adds <code>value</code> to the end of this list,\nextending the length by one.'));
+              'Adds <code>value</code> to the end of this list,\nextending the length by one. <a href="fake/SpecialList/add.html">[...]</a>'));
     });
 
     test(
diff --git a/testing/test_package_docs/ex/Apple-class.html b/testing/test_package_docs/ex/Apple-class.html
@@ -166,7 +166,7 @@ <h2>Properties</h2>
           </span>
         </dt>
         <dd>
-          The getter for <code>s</code>
+          The getter for <code>s</code> <a href="ex/Apple/s.html">[...]</a>
           <div class="features">read / write</div>
 </dd>
         <dt id="hashCode" class="property inherited">
@@ -206,7 +206,7 @@ <h2>Methods</h2>
           </span>
         </dt>
         <dd>
-          This is a method.
+          This is a method. <a href="ex/Apple/m1.html">[...]</a>
           
 </dd>
         <dt id="methodWithTypedefParam" class="callable">
diff --git a/testing/test_package_docs/ex/B-class.html b/testing/test_package_docs/ex/B-class.html
@@ -240,7 +240,7 @@ <h2>Methods</h2>
           </span>
         </dt>
         <dd>
-          This is a method.
+          This is a method. <a href="ex/B/m1.html">[...]</a>
           
 </dd>
         <dt id="writeMsg" class="callable">
diff --git a/testing/test_package_docs/ex/Dog-class.html b/testing/test_package_docs/ex/Dog-class.html
@@ -313,7 +313,7 @@ <h2>Methods</h2>
           </span>
         </dt>
         <dd>
-          Macro method
+          Macro method <a href="ex/Dog/withMacro.html">[...]</a>
           
 </dd>
         <dt id="withMacro2" class="callable">
diff --git a/testing/test_package_docs/ex/F-class.html b/testing/test_package_docs/ex/F-class.html
@@ -327,7 +327,7 @@ <h2>Methods</h2>
           </span>
         </dt>
         <dd class="inherited">
-          Macro method
+          Macro method <a href="ex/Dog/withMacro.html">[...]</a>
           <div class="features">inherited</div>
 </dd>
         <dt id="withMacro2" class="callable inherited">
diff --git a/testing/test_package_docs/ex/ex-library.html b/testing/test_package_docs/ex/ex-library.html
@@ -67,7 +67,7 @@ <h2>Classes</h2>
           <span class="name "><a href="ex/Apple-class.html">Apple</a></span>
         </dt>
         <dd>
-          Sample class <code>String</code>
+          Sample class <code>String</code> <a href="ex/Apple-class.html">[...]</a>
         </dd>
         <dt id="aThingToDo">
           <span class="name "><a href="ex/aThingToDo-class.html">aThingToDo</a></span>
@@ -79,7 +79,7 @@ <h2>Classes</h2>
           <span class="name "><a href="ex/B-class.html">B</a></span>
         </dt>
         <dd>
-          Extends class <a href="ex/Apple-class.html">Apple</a>, use <a href="ex/Apple/Apple.html">new Apple</a> or <a href="ex/Apple/Apple.fromString.html">new Apple.fromString</a>
+          Extends class <a href="ex/Apple-class.html">Apple</a>, use <a href="ex/Apple/Apple.html">new Apple</a> or <a href="ex/Apple/Apple.fromString.html">new Apple.fromString</a> <a href="ex/B-class.html">[...]</a>
         </dd>
         <dt id="Cat">
           <span class="name "><a href="ex/Cat-class.html">Cat</a></span>
@@ -115,7 +115,7 @@ <h2>Classes</h2>
           <span class="name "><a href="ex/Dog-class.html">Dog</a></span>
         </dt>
         <dd>
-          implements <a href="ex/Cat-class.html">Cat</a>, <a href="ex/E-class.html">E</a>
+          implements <a href="ex/Cat-class.html">Cat</a>, <a href="ex/E-class.html">E</a> <a href="ex/Dog-class.html">[...]</a>
         </dd>
         <dt id="E">
           <span class="name "><a href="ex/E-class.html">E</a></span>
@@ -171,7 +171,7 @@ <h2>Classes</h2>
           <span class="name "><a href="ex/ShapeType-class.html">ShapeType</a></span>
         </dt>
         <dd>
-          Foo bar.
+          Foo bar. <a href="ex/ShapeType-class.html">[...]</a>
         </dd>
         <dt id="SpecializedDuration">
           <span class="name "><a href="ex/SpecializedDuration-class.html">SpecializedDuration</a></span>
diff --git a/testing/test_package_docs/fake/BaseForDocComments-class.html b/testing/test_package_docs/fake/BaseForDocComments-class.html
@@ -186,7 +186,7 @@ <h2>Methods</h2>
           </span>
         </dt>
         <dd>
-          Takes a <code>value</code> and returns a String.
+          Takes a <code>value</code> and returns a String. <a href="fake/BaseForDocComments/doAwesomeStuff.html">[...]</a>
           
 </dd>
         <dt id="noSuchMethod" class="callable inherited">
diff --git a/testing/test_package_docs/fake/LongFirstLine-class.html b/testing/test_package_docs/fake/LongFirstLine-class.html
@@ -174,7 +174,7 @@ <h2>Constructors</h2>
           <span class="name"><a href="fake/LongFirstLine/LongFirstLine.fromMap.html">LongFirstLine.fromMap</a></span><span class="signature">(<span class="parameter" id="fromMap-param-data"><span class="type-annotation">Map</span> <span class="parameter-name">data</span></span>)</span>
         </dt>
         <dd>
-          Named constructors are awesome.
+          Named constructors are awesome. <a href="fake/LongFirstLine/LongFirstLine.fromMap.html">[...]</a>
         </dd>
       </dl>
     </section>
@@ -282,7 +282,7 @@ <h2>Methods</h2>
           </span>
         </dt>
         <dd class="inherited">
-          In the super class.
+          In the super class. <a href="fake/SuperAwesomeClass/fly.html">[...]</a>
           <div class="features">inherited</div>
 </dd>
         <dt id="noSuchMethod" class="callable inherited">
@@ -390,7 +390,7 @@ <h2>Static Methods</h2>
           </span>
         </dt>
         <dd>
-          Just a static method with no parameters.
+          Just a static method with no parameters. <a href="fake/LongFirstLine/staticMethodNoParams.html">[...]</a>
           
 </dd>
         <dt id="staticMethodReturnsVoid" class="callable">
diff --git a/testing/test_package_docs/fake/SubForDocComments-class.html b/testing/test_package_docs/fake/SubForDocComments-class.html
@@ -200,7 +200,7 @@ <h2>Methods</h2>
           </span>
         </dt>
         <dd class="inherited">
-          Takes a <code>value</code> and returns a String.
+          Takes a <code>value</code> and returns a String. <a href="fake/BaseForDocComments/doAwesomeStuff.html">[...]</a>
           <div class="features">inherited</div>
 </dd>
         <dt id="noSuchMethod" class="callable inherited">
diff --git a/testing/test_package_docs/fake/SuperAwesomeClass-class.html b/testing/test_package_docs/fake/SuperAwesomeClass-class.html
@@ -193,7 +193,7 @@ <h2>Methods</h2>
           </span>
         </dt>
         <dd>
-          In the super class.
+          In the super class. <a href="fake/SuperAwesomeClass/fly.html">[...]</a>
           
 </dd>
         <dt id="noSuchMethod" class="callable inherited">
diff --git a/testing/test_package_docs/fake/WithGetterAndSetter-class.html b/testing/test_package_docs/fake/WithGetterAndSetter-class.html
@@ -158,7 +158,7 @@ <h2>Properties</h2>
           </span>
         </dt>
         <dd>
-          Returns a length.
+          Returns a length. <a href="fake/WithGetterAndSetter/lengthX.html">[...]</a>
           <div class="features">read / write</div>
 </dd>
         <dt id="hashCode" class="property inherited">
diff --git a/testing/test_package_docs/fake/fake-library.html b/testing/test_package_docs/fake/fake-library.html
@@ -110,7 +110,7 @@ <h2>Classes</h2>
           <span class="name "><a href="fake/ConstantClass-class.html">ConstantClass</a></span>
         </dt>
         <dd>
-          For make-better testing of constants.
+          For make-better testing of constants. <a href="fake/ConstantClass-class.html">[...]</a>
         </dd>
         <dt id="Cool">
           <span class="name "><a href="fake/Cool-class.html">Cool</a></span>
@@ -160,7 +160,7 @@ <h2>Classes</h2>
         </dt>
         <dd>
           This is a very long line spread
-across... wait for it... two physical lines.
+across... wait for it... two physical lines. <a href="fake/LongFirstLine-class.html">[...]</a>
         </dd>
         <dt id="MixMeIn">
           <span class="name "><a href="fake/MixMeIn-class.html">MixMeIn</a></span>
@@ -326,7 +326,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; String</span>
         </dt>
         <dd>
-          Up is a direction.
+          Up is a direction. <a href="fake/UP-constant.html">[...]</a>
           
   <div>
             <span class="signature"><code>&#39;up&#39;</code></span>
@@ -399,7 +399,7 @@ <h2>Properties</h2>
           </span>
         </dt>
         <dd>
-          The getter for setAndGet.
+          The getter for setAndGet. <a href="fake/setAndGet.html">[...]</a>
           <div class="features">read / write</div>
 </dd>
         <dt id="simpleProperty" class="property">
@@ -442,7 +442,7 @@ <h2>Functions</h2>
           </span>
         </dt>
         <dd>
-          This function has two parameters that are functions.
+          This function has two parameters that are functions. <a href="fake/functionWithFunctionParameters.html">[...]</a>
           
 </dd>
         <dt id="myGenericFunction" class="callable">
@@ -496,7 +496,7 @@ <h2>Functions</h2>
           </span>
         </dt>
         <dd>
-          Testing <a href="fake/NAME_WITH_TWO_UNDERSCORES-constant.html">NAME_WITH_TWO_UNDERSCORES</a> should not be italicized.
+          Testing <a href="fake/NAME_WITH_TWO_UNDERSCORES-constant.html">NAME_WITH_TWO_UNDERSCORES</a> should not be italicized. <a href="fake/short.html">[...]</a>
           
 </dd>
         <dt id="soIntense" class="callable">
@@ -533,7 +533,7 @@ <h2>Functions</h2>
           </span>
         </dt>
         <dd>
-          Top-level function 3 params and 1 optional positional param.
+          Top-level function 3 params and 1 optional positional param. <a href="fake/topLevelFunction.html">[...]</a>
           
 </dd>
       </dl>
diff --git a/testing/test_package_docs/index.html b/testing/test_package_docs/index.html
@@ -93,7 +93,7 @@ <h2>Libraries</h2>
               <code class="language-dart">void main() {
   // in Dart!
 }
-</code>
+</code> <a href="code_in_comments/code_in_comments-library.html">[...]</a>
             </dd>
             <dt id="css">
               <span class="name"><a href="css/css-library.html">css</a></span>
@@ -112,7 +112,7 @@ <h2>Libraries</h2>
               <span class="name"><a href="fake/fake-library.html">fake</a></span>
             </dt>
             <dd>
-              WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a>
+              WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a> <a href="fake/fake-library.html">[...]</a>
             </dd>
             <dt id="is_deprecated">
               <span class="name"><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></span>
diff --git a/testing/test_package_docs/two_exports/BaseClass-class.html b/testing/test_package_docs/two_exports/BaseClass-class.html
@@ -105,7 +105,7 @@ <h2>Properties</h2>
           </span>
         </dt>
         <dd class="inherited">
-          Returns a length.
+          Returns a length. <a href="fake/WithGetterAndSetter/lengthX.html">[...]</a>
           <div class="features">read / write, inherited</div>
 </dd>
         <dt id="runtimeType" class="property inherited">
diff --git a/testing/test_package_docs/two_exports/ExtendingClass-class.html b/testing/test_package_docs/two_exports/ExtendingClass-class.html
@@ -107,7 +107,7 @@ <h2>Properties</h2>
           </span>
         </dt>
         <dd class="inherited">
-          Returns a length.
+          Returns a length. <a href="fake/WithGetterAndSetter/lengthX.html">[...]</a>
           <div class="features">read / write, inherited</div>
 </dd>
         <dt id="runtimeType" class="property inherited">
diff --git a/testing/test_package_docs/two_exports/two_exports-library.html b/testing/test_package_docs/two_exports/two_exports-library.html
@@ -70,7 +70,7 @@ <h2>Classes</h2>
           <span class="name "><a href="two_exports/ExtendingClass-class.html">ExtendingClass</a></span>
         </dt>
         <dd>
-          Extending class extends <a href="two_exports/BaseClass-class.html">BaseClass</a>.
+          Extending class extends <a href="two_exports/BaseClass-class.html">BaseClass</a>. <a href="two_exports/ExtendingClass-class.html">[...]</a>
         </dd>
       </dl>
     </section>
