fix issues with dispaying constants

CHANGELOG.md

@@ -1,4 +1,9 @@
 
+## 0.9.7+1
+* change how we truncate long constant values on the summary page
+* show the full docs for enums on the summary page; just show the first line of
+  docs for other contants
+
 ## 0.9.7
 * fix the display of long constants
 * fixed an issue with duplicate libraries in SDK

lib/dartdoc.dart

@@ -40,7 +40,7 @@ export 'src/package_meta.dart';
 
 const String name = 'dartdoc';
 // Update when pubspec version changes.
-const String version = '0.9.7';
+const String version = '0.9.7+1';
 
 final String defaultOutDir = p.join('doc', 'api');
 

lib/resources/styles.css

@@ -305,14 +305,6 @@ dl dt.callable .name {
   color: #4674a2;
 }
 
-/* make sure constant values don't overflow */
-.signature code {
-  white-space: nowrap;
-  overflow-x: hidden;
-  text-overflow: ellipsis;
-  display: block;
-}
-
 .optional {
   font-style: italic;
 }

lib/src/markdown_processor.dart

@@ -189,7 +189,8 @@ class Documentation {
 
       if (pre.children.isNotEmpty && pre.children.first.localName == 'code') {
         var code = pre.children.first;
-        pre.classes.addAll(code.classes.where((name) => name.startsWith('language-')));
+        pre.classes
+            .addAll(code.classes.where((name) => name.startsWith('language-')));
       }
 
       bool specifiesLanguage = pre.classes.isNotEmpty;
@@ -203,6 +204,9 @@ class Documentation {
     var asOneLiner = asHtmlDocument.body.children.isEmpty
         ? ''
         : asHtmlDocument.body.children.first.innerHtml;
+    if (!asOneLiner.startsWith('<p>')) {
+      asOneLiner = '<p>$asOneLiner</p>';
+    }
     return new Documentation._(markdown, asHtml, asOneLiner);
   }
 }

lib/src/model.dart

@@ -26,7 +26,7 @@ import 'line_number_cache.dart';
 import 'markdown_processor.dart' show Documentation;
 import 'model_utils.dart';
 import 'package_meta.dart' show PackageMeta, FileContents;
-import 'utils.dart' show stripComments;
+import 'utils.dart';
 
 Map<String, Map<String, List<Map<String, dynamic>>>> __crossdartJson;
 
@@ -772,6 +772,9 @@ class EnumField extends Field {
     }
   }
 
+  @override
+  String get oneLineDoc => documentationAsHtml;
+
   @override
   String get href =>
       '${library.dirName}/${(enclosingElement as Class).fileName}';
@@ -809,6 +812,8 @@ class Field extends ModelElement
     return _constantValue;
   }
 
+  String get constantValueTruncated => truncateString(constantValue, 200);
+
   @override
   ModelElement get enclosingElement {
     if (_enclosingClass == null) {
@@ -1531,7 +1536,6 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
 
   String linkedParams(
       {bool showMetadata: true, bool showNames: true, String separator: ', '}) {
-
     String renderParam(Parameter param, String suffix) {
       StringBuffer buf = new StringBuffer();
       buf.write('<span class="parameter" id="${param.htmlId}">');
@@ -2165,6 +2169,8 @@ class TopLevelVariable extends ModelElement
     return string.replaceAll(modelType.name, modelType.linkedName);
   }
 
+  String get constantValueTruncated => truncateString(constantValue, 200);
+
   @override
   ModelElement get enclosingElement => library;
 

lib/src/utils.dart

@@ -41,3 +41,11 @@ String stripComments(String str) {
   }
   return buf.toString().trim();
 }
+
+String truncateString(String str, int length) {
+  if (str != null && str.length > length) {
+    return str.substring(0, length) + '…';
+  } else {
+    return str;
+  }
+}

lib/templates/_callable.html

@@ -4,7 +4,7 @@
   </span>
 </dt>
 <dd{{ #isInherited }} class="inherited"{{ /isInherited}}>
-  <p>{{{ oneLineDoc }}}</p>
+  {{{ oneLineDoc }}}
   {{#isInherited}}
   <div class="features">inherited</div>
   {{/isInherited}}

lib/templates/_constant.html

@@ -3,8 +3,8 @@
   <span class="signature">&#8594; {{{ linkedReturnType }}}</span>
 </dt>
 <dd>
-  {{{ documentationAsHtml }}}
+  {{{ oneLineDoc }}}
   <div>
-    <span class="signature"><code>{{{ constantValue }}}</code></span>
+    <span class="signature"><code>{{{ constantValueTruncated }}}</code></span>
   </div>
 </dd>

lib/templates/_property.html

@@ -3,6 +3,6 @@
   <span class="signature">&#8594; {{{ linkedReturnType }}}</span>
 </dt>
 <dd{{ #isInherited }} class="inherited"{{ /isInherited}}>
-  <p>{{{ oneLineDoc }}}</p>
+  {{{ oneLineDoc }}}
   {{>readable_writable}}
 </dd>

lib/templates/class.html

@@ -114,7 +114,7 @@ <h2>Constructors</h2>
           <span class="name">{{{linkedName}}}</span><span class="signature">({{{ linkedParams }}})</span>
         </dt>
         <dd>
-          <p>{{{ oneLineDoc }}}</p>
+          {{{ oneLineDoc }}}
           {{#isConst}}
           <div class="constructor-modifier features">const</div>
           {{/isConst}}

lib/templates/index.html

@@ -40,7 +40,7 @@ <h2>{{name}}</h2>
                 <span class="name">{{{ linkedName }}}</span>
               </dt>
               <dd>
-                {{#isDocumented}}<p>{{{ oneLineDoc }}}</p>{{/isDocumented}}
+                {{#isDocumented}}{{{ oneLineDoc }}}{{/isDocumented}}
               </dd>
             {{/libraries}}
           </dl>
@@ -58,7 +58,7 @@ <h2>Libraries</h2>
               <span class="name">{{{ linkedName }}}</span>
             </dt>
             <dd>
-              {{#isDocumented}}<p>{{{ oneLineDoc }}}</p>{{/isDocumented}}
+              {{#isDocumented}}{{{ oneLineDoc }}}{{/isDocumented}}
             </dd>
           {{/package.libraries}}
         </dl>

lib/templates/library.html

@@ -91,7 +91,7 @@ <h2>Enums</h2>
           {{{linkedName}}}
         </dt>
         <dd>
-          <p>{{{ oneLineDoc }}}</p>
+          {{{ oneLineDoc }}}
         </dd>
         {{/library.enums}}
       </dl>
@@ -108,7 +108,7 @@ <h2>Classes</h2>
           <span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{{linkedName}}}</span>
         </dt>
         <dd>
-          <p>{{{ oneLineDoc }}}</p>
+          {{{ oneLineDoc }}}
         </dd>
         {{/library.classes}}
       </dl>
@@ -125,7 +125,7 @@ <h2>Exceptions / Errors</h2>
           <span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{{linkedName}}}</span>
         </dt>
         <dd>
-          <p>{{{ oneLineDoc }}}</p>
+          {{{ oneLineDoc }}}
         </dd>
         {{/library.exceptions}}
       </dl>

pubspec.yaml

@@ -1,6 +1,6 @@
 name: dartdoc
 # Also update the `version` field in lib/dartdoc.dart.
-version: 0.9.7
+version: 0.9.7+1
 author: Dart Team <misc@dartlang.org>
 description: A documentation generator for Dart.
 homepage: https://github.com/dart-lang/dartdoc

test/model_test.dart

@@ -162,7 +162,7 @@ void main() {
       expect(
           fakeLibrary.oneLineDoc,
           equals(
-              'WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a>'));
+              '<p>WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a></p>'));
     });
 
     test('has properties', () {
@@ -379,7 +379,7 @@ void main() {
       expect(
           add.oneLineDoc,
           equals(
-              'Adds <code>value</code> to the end of this list,\nextending the length by one.'));
+              '<p>Adds <code>value</code> to the end of this list,\nextending the length by one.</p>'));
     });
 
     test(
@@ -459,7 +459,7 @@ void main() {
       expect(
           testingCodeSyntaxInOneLiners.oneLineDoc,
           equals(
-              'These are code syntaxes: <code>true</code> and <code>false</code>'));
+              '<p>These are code syntaxes: <code>true</code> and <code>false</code></p>'));
     });
 
     test('doc comments to parameters are marked as code', () {
@@ -1467,7 +1467,8 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
     });
 
     test('commas on same param line', () {
-      ModelFunction method = fakeLibrary.functions.firstWhere((f) => f.name == 'paintImage1');
+      ModelFunction method =
+          fakeLibrary.functions.firstWhere((f) => f.name == 'paintImage1');
       String params = method.linkedParams();
       expect(params, contains(', </span>'));
     });

test/utils_test.dart

@@ -165,4 +165,15 @@ void main() {
       expectCorrectDocumentation();
     });
   });
+
+  group('truncateString', () {
+    test('normal', () {
+      expect(truncateString('foo bar baz qux', 100), hasLength(15));
+    });
+
+    test('truncates', () {
+      expect(truncateString('foo bar baz qux', 10), hasLength(11));
+      expect(truncateString('foo bar baz qux', 10), 'foo bar ba…');
+    });
+  });
 }

testing/test_package/lib/fake.dart

@@ -256,6 +256,11 @@ enum Color {
   ORANGE,
   YELLOW,
   GREEN,
+
+  /// Some constants have long docs.
+  ///
+  /// Some constants have long docs.
+  /// Some constants have long docs.
   BLUE,
   INDIGO,
   VIOLET

testing/test_package_docs/ex/Animal-class.html

@@ -203,7 +203,7 @@ <h2>Properties</h2>
           <span class="signature">&#8594; int</span>
         </dt>
         <dd>
-          <p></p>
+
           <div class="features">
     read-only
   </div>

testing/test_package_docs/ex/Apple-class.html

@@ -163,7 +163,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; int</span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>5</code></span>
           </div>

testing/test_package_docs/ex/ShapeType-class.html

@@ -151,7 +151,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; <a href="ex/ShapeType-class.html">ShapeType</a></span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>const <a href="ex/ShapeType-class.html">ShapeType</a>._internal("Ellipse")</code></span>
           </div>
@@ -161,7 +161,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; <a href="ex/ShapeType-class.html">ShapeType</a></span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>const <a href="ex/ShapeType-class.html">ShapeType</a>._internal("Rect")</code></span>
           </div>

testing/test_package_docs/ex/ex-library.html

@@ -104,7 +104,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; String</span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>&#39;red&#39;</code></span>
           </div>
@@ -114,7 +114,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; String</span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>&#39;green&#39;</code></span>
           </div>
@@ -124,7 +124,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; String</span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>&#39;orange&#39;</code></span>
           </div>
@@ -134,7 +134,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; String</span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>&#39;red&#39; + &#39;-&#39; + &#39;green&#39; + &#39;-&#39; + &#39;blue&#39;</code></span>
           </div>
@@ -174,7 +174,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; <a href="ex/ConstantCat-class.html">ConstantCat</a></span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>const <a href="ex/ConstantCat-class.html">ConstantCat</a>(&#39;tabby&#39;)</code></span>
           </div>
@@ -184,7 +184,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; List&lt;String&gt;</span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>const &lt;String&gt; [COLOR_GREEN, COLOR_ORANGE, &#39;blue&#39;]</code></span>
           </div>

testing/test_package_docs/fake/Color-class.html

@@ -163,7 +163,9 @@ <h2>Constants</h2>
           <span class="signature">&#8594; <a href="fake/Color-class.html">Color</a></span>
         </dt>
         <dd>
-
+          <p>Some constants have long docs.</p>
+<p>Some constants have long docs.
+Some constants have long docs.</p>
           <div>
             <span class="signature"><code>const Color(4)</code></span>
           </div>
@@ -263,7 +265,7 @@ <h2>Properties</h2>
           <span class="signature">&#8594; int</span>
         </dt>
         <dd>
-          <p></p>
+
           <div class="features">
     read-only
   </div>

testing/test_package_docs/fake/Foo2-class.html

@@ -166,7 +166,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; <a href="fake/Foo2-class.html">Foo2</a></span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>const <a href="fake/Foo2-class.html">Foo2</a>(0)</code></span>
           </div>
@@ -176,7 +176,7 @@ <h2>Constants</h2>
           <span class="signature">&#8594; <a href="fake/Foo2-class.html">Foo2</a></span>
         </dt>
         <dd>
-
+          <p></p>
           <div>
             <span class="signature"><code>const <a href="fake/Foo2-class.html">Foo2</a>(1)</code></span>
           </div>