Skip to content

Commit f8cd4c8

Browse files
devoncarewdevoncarew
authored
Merge pull request #1224 from dart-lang/change_constant_display
fix issues with dispaying constants
2 parents ff194f4 + 3417bb1 commit f8cd4c8

26 files changed

+85
-60
lines changed

‎CHANGELOG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11

2+
## 0.9.7+1
3+
* change how we truncate long constant values on the summary page
4+
* show the full docs for enums on the summary page; just show the first line of
5+
docs for other contants
6+
27
## 0.9.7
38
* fix the display of long constants
49
* fixed an issue with duplicate libraries in SDK

‎lib/dartdoc.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ export 'src/package_meta.dart';
4040

4141
const String name = 'dartdoc';
4242
// Update when pubspec version changes.
43-
const String version = '0.9.7';
43+
const String version = '0.9.7+1';
4444

4545
final String defaultOutDir = p.join('doc', 'api');
4646

‎lib/resources/styles.css

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -305,14 +305,6 @@ dl dt.callable .name {
305305
color: #4674a2;
306306
}
307307

308-
/* make sure constant values don't overflow */
309-
.signature code {
310-
white-space: nowrap;
311-
overflow-x: hidden;
312-
text-overflow: ellipsis;
313-
display: block;
314-
}
315-
316308
.optional {
317309
font-style: italic;
318310
}

‎lib/src/markdown_processor.dart

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,8 @@ class Documentation {
189189

190190
if (pre.children.isNotEmpty && pre.children.first.localName == 'code') {
191191
var code = pre.children.first;
192-
pre.classes.addAll(code.classes.where((name) => name.startsWith('language-')));
192+
pre.classes
193+
.addAll(code.classes.where((name) => name.startsWith('language-')));
193194
}
194195

195196
bool specifiesLanguage = pre.classes.isNotEmpty;
@@ -203,6 +204,9 @@ class Documentation {
203204
var asOneLiner = asHtmlDocument.body.children.isEmpty
204205
? ''
205206
: asHtmlDocument.body.children.first.innerHtml;
207+
if (!asOneLiner.startsWith('<p>')) {
208+
asOneLiner = '<p>$asOneLiner</p>';
209+
}
206210
return new Documentation._(markdown, asHtml, asOneLiner);
207211
}
208212
}

‎lib/src/model.dart

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ import 'line_number_cache.dart';
2626
import 'markdown_processor.dart' show Documentation;
2727
import 'model_utils.dart';
2828
import 'package_meta.dart' show PackageMeta, FileContents;
29-
import 'utils.dart' show stripComments;
29+
import 'utils.dart';
3030

3131
Map<String, Map<String, List<Map<String, dynamic>>>> __crossdartJson;
3232

@@ -772,6 +772,9 @@ class EnumField extends Field {
772772
}
773773
}
774774

775+
@override
776+
String get oneLineDoc => documentationAsHtml;
777+
775778
@override
776779
String get href =>
777780
'${library.dirName}/${(enclosingElement as Class).fileName}';
@@ -809,6 +812,8 @@ class Field extends ModelElement
809812
return _constantValue;
810813
}
811814

815+
String get constantValueTruncated => truncateString(constantValue, 200);
816+
812817
@override
813818
ModelElement get enclosingElement {
814819
if (_enclosingClass == null) {
@@ -1531,7 +1536,6 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
15311536

15321537
String linkedParams(
15331538
{bool showMetadata: true, bool showNames: true, String separator: ', '}) {
1534-
15351539
String renderParam(Parameter param, String suffix) {
15361540
StringBuffer buf = new StringBuffer();
15371541
buf.write('<span class="parameter" id="${param.htmlId}">');
@@ -2165,6 +2169,8 @@ class TopLevelVariable extends ModelElement
21652169
return string.replaceAll(modelType.name, modelType.linkedName);
21662170
}
21672171

2172+
String get constantValueTruncated => truncateString(constantValue, 200);
2173+
21682174
@override
21692175
ModelElement get enclosingElement => library;
21702176

‎lib/src/utils.dart

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,11 @@ String stripComments(String str) {
4141
}
4242
return buf.toString().trim();
4343
}
44+
45+
String truncateString(String str, int length) {
46+
if (str != null && str.length > length) {
47+
return str.substring(0, length) + '…';
48+
} else {
49+
return str;
50+
}
51+
}

‎lib/templates/_callable.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
</span>
55
</dt>
66
<dd{{ #isInherited }} class="inherited"{{ /isInherited}}>
7-
<p>{{{ oneLineDoc }}}</p>
7+
{{{ oneLineDoc }}}
88
{{#isInherited}}
99
<div class="features">inherited</div>
1010
{{/isInherited}}

‎lib/templates/_constant.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
<span class="signature">&#8594; {{{ linkedReturnType }}}</span>
44
</dt>
55
<dd>
6-
{{{ documentationAsHtml }}}
6+
{{{ oneLineDoc }}}
77
<div>
8-
<span class="signature"><code>{{{ constantValue }}}</code></span>
8+
<span class="signature"><code>{{{ constantValueTruncated }}}</code></span>
99
</div>
1010
</dd>

‎lib/templates/_property.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,6 @@
33
<span class="signature">&#8594; {{{ linkedReturnType }}}</span>
44
</dt>
55
<dd{{ #isInherited }} class="inherited"{{ /isInherited}}>
6-
<p>{{{ oneLineDoc }}}</p>
6+
{{{ oneLineDoc }}}
77
{{>readable_writable}}
88
</dd>

‎lib/templates/class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ <h2>Constructors</h2>
114114
<span class="name">{{{linkedName}}}</span><span class="signature">({{{ linkedParams }}})</span>
115115
</dt>
116116
<dd>
117-
<p>{{{ oneLineDoc }}}</p>
117+
{{{ oneLineDoc }}}
118118
{{#isConst}}
119119
<div class="constructor-modifier features">const</div>
120120
{{/isConst}}

‎lib/templates/index.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ <h2>{{name}}</h2>
4040
<span class="name">{{{ linkedName }}}</span>
4141
</dt>
4242
<dd>
43-
{{#isDocumented}}<p>{{{ oneLineDoc }}}</p>{{/isDocumented}}
43+
{{#isDocumented}}{{{ oneLineDoc }}}{{/isDocumented}}
4444
</dd>
4545
{{/libraries}}
4646
</dl>
@@ -58,7 +58,7 @@ <h2>Libraries</h2>
5858
<span class="name">{{{ linkedName }}}</span>
5959
</dt>
6060
<dd>
61-
{{#isDocumented}}<p>{{{ oneLineDoc }}}</p>{{/isDocumented}}
61+
{{#isDocumented}}{{{ oneLineDoc }}}{{/isDocumented}}
6262
</dd>
6363
{{/package.libraries}}
6464
</dl>

‎lib/templates/library.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ <h2>Enums</h2>
9191
{{{linkedName}}}
9292
</dt>
9393
<dd>
94-
<p>{{{ oneLineDoc }}}</p>
94+
{{{ oneLineDoc }}}
9595
</dd>
9696
{{/library.enums}}
9797
</dl>
@@ -108,7 +108,7 @@ <h2>Classes</h2>
108108
<span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{{linkedName}}}</span>
109109
</dt>
110110
<dd>
111-
<p>{{{ oneLineDoc }}}</p>
111+
{{{ oneLineDoc }}}
112112
</dd>
113113
{{/library.classes}}
114114
</dl>
@@ -125,7 +125,7 @@ <h2>Exceptions / Errors</h2>
125125
<span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{{linkedName}}}</span>
126126
</dt>
127127
<dd>
128-
<p>{{{ oneLineDoc }}}</p>
128+
{{{ oneLineDoc }}}
129129
</dd>
130130
{{/library.exceptions}}
131131
</dl>

‎pubspec.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
name: dartdoc
22
# Also update the `version` field in lib/dartdoc.dart.
3-
version: 0.9.7
3+
version: 0.9.7+1
44
author: Dart Team <misc@dartlang.org>
55
description: A documentation generator for Dart.
66
homepage: https://github.com/dart-lang/dartdoc

‎test/model_test.dart

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ void main() {
162162
expect(
163163
fakeLibrary.oneLineDoc,
164164
equals(
165-
'WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a>'));
165+
'<p>WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a></p>'));
166166
});
167167

168168
test('has properties', () {
@@ -379,7 +379,7 @@ void main() {
379379
expect(
380380
add.oneLineDoc,
381381
equals(
382-
'Adds <code>value</code> to the end of this list,\nextending the length by one.'));
382+
'<p>Adds <code>value</code> to the end of this list,\nextending the length by one.</p>'));
383383
});
384384

385385
test(
@@ -459,7 +459,7 @@ void main() {
459459
expect(
460460
testingCodeSyntaxInOneLiners.oneLineDoc,
461461
equals(
462-
'These are code syntaxes: <code>true</code> and <code>false</code>'));
462+
'<p>These are code syntaxes: <code>true</code> and <code>false</code></p>'));
463463
});
464464

465465
test('doc comments to parameters are marked as code', () {
@@ -1467,7 +1467,8 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
14671467
});
14681468

14691469
test('commas on same param line', () {
1470-
ModelFunction method = fakeLibrary.functions.firstWhere((f) => f.name == 'paintImage1');
1470+
ModelFunction method =
1471+
fakeLibrary.functions.firstWhere((f) => f.name == 'paintImage1');
14711472
String params = method.linkedParams();
14721473
expect(params, contains(', </span>'));
14731474
});

‎test/utils_test.dart

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,4 +165,15 @@ void main() {
165165
expectCorrectDocumentation();
166166
});
167167
});
168+
169+
group('truncateString', () {
170+
test('normal', () {
171+
expect(truncateString('foo bar baz qux', 100), hasLength(15));
172+
});
173+
174+
test('truncates', () {
175+
expect(truncateString('foo bar baz qux', 10), hasLength(11));
176+
expect(truncateString('foo bar baz qux', 10), 'foo bar ba…');
177+
});
178+
});
168179
}

‎testing/test_package/lib/fake.dart

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -256,6 +256,11 @@ enum Color {
256256
ORANGE,
257257
YELLOW,
258258
GREEN,
259+
260+
/// Some constants have long docs.
261+
///
262+
/// Some constants have long docs.
263+
/// Some constants have long docs.
259264
BLUE,
260265
INDIGO,
261266
VIOLET

‎testing/test_package_docs/ex/Animal-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ <h2>Properties</h2>
203203
<span class="signature">&#8594; int</span>
204204
</dt>
205205
<dd>
206-
<p></p>
206+
207207
<div class="features">
208208
read-only
209209
</div>

‎testing/test_package_docs/ex/Apple-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,7 @@ <h2>Constants</h2>
163163
<span class="signature">&#8594; int</span>
164164
</dt>
165165
<dd>
166-
166+
<p></p>
167167
<div>
168168
<span class="signature"><code>5</code></span>
169169
</div>

‎testing/test_package_docs/ex/ShapeType-class.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ <h2>Constants</h2>
151151
<span class="signature">&#8594; <a href="ex/ShapeType-class.html">ShapeType</a></span>
152152
</dt>
153153
<dd>
154-
154+
<p></p>
155155
<div>
156156
<span class="signature"><code>const <a href="ex/ShapeType-class.html">ShapeType</a>._internal("Ellipse")</code></span>
157157
</div>
@@ -161,7 +161,7 @@ <h2>Constants</h2>
161161
<span class="signature">&#8594; <a href="ex/ShapeType-class.html">ShapeType</a></span>
162162
</dt>
163163
<dd>
164-
164+
<p></p>
165165
<div>
166166
<span class="signature"><code>const <a href="ex/ShapeType-class.html">ShapeType</a>._internal("Rect")</code></span>
167167
</div>

‎testing/test_package_docs/ex/ex-library.html

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ <h2>Constants</h2>
104104
<span class="signature">&#8594; String</span>
105105
</dt>
106106
<dd>
107-
107+
<p></p>
108108
<div>
109109
<span class="signature"><code>&#39;red&#39;</code></span>
110110
</div>
@@ -114,7 +114,7 @@ <h2>Constants</h2>
114114
<span class="signature">&#8594; String</span>
115115
</dt>
116116
<dd>
117-
117+
<p></p>
118118
<div>
119119
<span class="signature"><code>&#39;green&#39;</code></span>
120120
</div>
@@ -124,7 +124,7 @@ <h2>Constants</h2>
124124
<span class="signature">&#8594; String</span>
125125
</dt>
126126
<dd>
127-
127+
<p></p>
128128
<div>
129129
<span class="signature"><code>&#39;orange&#39;</code></span>
130130
</div>
@@ -134,7 +134,7 @@ <h2>Constants</h2>
134134
<span class="signature">&#8594; String</span>
135135
</dt>
136136
<dd>
137-
137+
<p></p>
138138
<div>
139139
<span class="signature"><code>&#39;red&#39; + &#39;-&#39; + &#39;green&#39; + &#39;-&#39; + &#39;blue&#39;</code></span>
140140
</div>
@@ -174,7 +174,7 @@ <h2>Constants</h2>
174174
<span class="signature">&#8594; <a href="ex/ConstantCat-class.html">ConstantCat</a></span>
175175
</dt>
176176
<dd>
177-
177+
<p></p>
178178
<div>
179179
<span class="signature"><code>const <a href="ex/ConstantCat-class.html">ConstantCat</a>(&#39;tabby&#39;)</code></span>
180180
</div>
@@ -184,7 +184,7 @@ <h2>Constants</h2>
184184
<span class="signature">&#8594; List&lt;String&gt;</span>
185185
</dt>
186186
<dd>
187-
187+
<p></p>
188188
<div>
189189
<span class="signature"><code>const &lt;String&gt; [COLOR_GREEN, COLOR_ORANGE, &#39;blue&#39;]</code></span>
190190
</div>

‎testing/test_package_docs/fake/Color-class.html

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,9 @@ <h2>Constants</h2>
163163
<span class="signature">&#8594; <a href="fake/Color-class.html">Color</a></span>
164164
</dt>
165165
<dd>
166-
166+
<p>Some constants have long docs.</p>
167+
<p>Some constants have long docs.
168+
Some constants have long docs.</p>
167169
<div>
168170
<span class="signature"><code>const Color(4)</code></span>
169171
</div>
@@ -263,7 +265,7 @@ <h2>Properties</h2>
263265
<span class="signature">&#8594; int</span>
264266
</dt>
265267
<dd>
266-
<p></p>
268+
267269
<div class="features">
268270
read-only
269271
</div>

‎testing/test_package_docs/fake/Foo2-class.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ <h2>Constants</h2>
166166
<span class="signature">&#8594; <a href="fake/Foo2-class.html">Foo2</a></span>
167167
</dt>
168168
<dd>
169-
169+
<p></p>
170170
<div>
171171
<span class="signature"><code>const <a href="fake/Foo2-class.html">Foo2</a>(0)</code></span>
172172
</div>
@@ -176,7 +176,7 @@ <h2>Constants</h2>
176176
<span class="signature">&#8594; <a href="fake/Foo2-class.html">Foo2</a></span>
177177
</dt>
178178
<dd>
179-
179+
<p></p>
180180
<div>
181181
<span class="signature"><code>const <a href="fake/Foo2-class.html">Foo2</a>(1)</code></span>
182182
</div>

0 commit comments

Comments
 (0)