Skip to content

Commit 3f2aa82

Browse files
devoncarewdevoncarew
authored
Merge pull request #1212 from dart-lang/param_formatting
better formatting for method params
2 parents bd682be + bd10c53 commit 3f2aa82

File tree

121 files changed

+1172
-158
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

121 files changed

+1172
-158
lines changed

‎lib/resources/styles.css

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -413,8 +413,11 @@ footer .container-fluid {
413413
.multi-line-signature {
414414
font-size: 17px;
415415
color: #727272;
416+
}
417+
418+
.multi-line-signature .parameter {
416419
margin-left: 24px;
417-
text-indent: -24px;
420+
display: block;
418421
}
419422

420423
.breadcrumbs {

‎lib/src/model.dart

Lines changed: 61 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1530,36 +1530,35 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
15301530

15311531
String linkedParams(
15321532
{bool showMetadata: true, bool showNames: true, String separator: ', '}) {
1533-
String renderParam(Parameter p) {
1533+
1534+
String renderParam(Parameter param, String suffix) {
15341535
StringBuffer buf = new StringBuffer();
1535-
buf.write('<span class="parameter" id="${p.htmlId}">');
1536-
if (showMetadata && p.hasAnnotations) {
1537-
buf.write('<ol class="annotation-list">');
1538-
p.annotations.forEach((String annotation) {
1539-
buf.write('<li>$annotation</li>');
1536+
buf.write('<span class="parameter" id="${param.htmlId}">');
1537+
if (showMetadata && param.hasAnnotations) {
1538+
param.annotations.forEach((String annotation) {
1539+
buf.write('<span>@$annotation</span> ');
15401540
});
1541-
buf.write('</ol> ');
15421541
}
1543-
if (p.modelType.isFunctionType) {
1542+
if (param.modelType.isFunctionType) {
15441543
var returnTypeName;
1545-
bool isTypedef = p.modelType.element is Typedef;
1544+
bool isTypedef = param.modelType.element is Typedef;
15461545
if (isTypedef) {
1547-
returnTypeName = p.modelType.linkedName;
1546+
returnTypeName = param.modelType.linkedName;
15481547
} else {
1549-
returnTypeName = p.modelType.createLinkedReturnTypeName();
1548+
returnTypeName = param.modelType.createLinkedReturnTypeName();
15501549
}
15511550
buf.write('<span class="type-annotation">${returnTypeName}</span>');
15521551
if (showNames) {
1553-
buf.write(' <span class="parameter-name">${p.name}</span>');
1552+
buf.write(' <span class="parameter-name">${param.name}</span>');
15541553
}
15551554
if (!isTypedef) {
15561555
buf.write('(');
1557-
buf.write(p.modelType.element
1556+
buf.write(param.modelType.element
15581557
.linkedParams(showNames: showNames, showMetadata: showMetadata));
15591558
buf.write(')');
15601559
}
1561-
} else if (p.modelType != null && p.modelType.element != null) {
1562-
var mt = p.modelType;
1560+
} else if (param.modelType != null && param.modelType.element != null) {
1561+
var mt = param.modelType;
15631562
String typeName = "";
15641563
if (mt != null && !mt.isDynamic) {
15651564
typeName = mt.linkedName;
@@ -1568,46 +1567,71 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
15681567
buf.write('<span class="type-annotation">$typeName</span> ');
15691568
}
15701569
if (showNames) {
1571-
buf.write('<span class="parameter-name">${p.name}</span>');
1570+
buf.write('<span class="parameter-name">${param.name}</span>');
15721571
}
15731572
}
15741573

1575-
if (p.hasDefaultValue) {
1576-
if (p.isOptionalNamed) {
1574+
if (param.hasDefaultValue) {
1575+
if (param.isOptionalNamed) {
15771576
buf.write(': ');
15781577
} else {
15791578
buf.write(' = ');
15801579
}
1581-
buf.write('<span class="default-value">${p.defaultValue}</span>');
1580+
buf.write('<span class="default-value">${param.defaultValue}</span>');
15821581
}
1583-
buf.write('</span>');
1582+
buf.write('${suffix}</span>');
15841583
return buf.toString();
15851584
}
15861585

1587-
String renderParams(Iterable<Parameter> params,
1588-
{String open: '', String close: ''}) {
1589-
return '$open${params.map(renderParam).join(separator)}$close';
1590-
}
1586+
List<Parameter> requiredParams =
1587+
parameters.where((Parameter p) => !p.isOptional).toList();
1588+
List<Parameter> positionalParams =
1589+
parameters.where((Parameter p) => p.isOptionalPositional).toList();
1590+
List<Parameter> namedParams =
1591+
parameters.where((Parameter p) => p.isOptionalNamed).toList();
15911592

1592-
Iterable<Parameter> requiredParams =
1593-
parameters.where((Parameter p) => !p.isOptional);
1594-
Iterable<Parameter> positionalParams =
1595-
parameters.where((Parameter p) => p.isOptionalPositional);
1596-
Iterable<Parameter> namedParams =
1597-
parameters.where((Parameter p) => p.isOptionalNamed);
1593+
StringBuffer builder = new StringBuffer();
1594+
1595+
// prefix
1596+
if (requiredParams.isEmpty && positionalParams.isNotEmpty) {
1597+
builder.write('[');
1598+
} else if (requiredParams.isEmpty && namedParams.isNotEmpty) {
1599+
builder.write('{');
1600+
}
15981601

1599-
List<String> fragments = [];
1600-
if (requiredParams.isNotEmpty) {
1601-
fragments.add(renderParams(requiredParams));
1602+
// index over params
1603+
for (Parameter param in requiredParams) {
1604+
bool isLast = param == requiredParams.last;
1605+
String ext;
1606+
if (isLast && positionalParams.isNotEmpty) {
1607+
ext = ', [';
1608+
} else if (isLast && namedParams.isNotEmpty) {
1609+
ext = ', {';
1610+
} else {
1611+
ext = isLast ? '' : ', ';
1612+
}
1613+
builder.write(renderParam(param, ext));
1614+
builder.write(' ');
16021615
}
1603-
if (positionalParams.isNotEmpty) {
1604-
fragments.add(renderParams(positionalParams, open: '[', close: ']'));
1616+
for (Parameter param in positionalParams) {
1617+
bool isLast = param == positionalParams.last;
1618+
builder.write(renderParam(param, isLast ? '' : ', '));
1619+
builder.write(' ');
16051620
}
1621+
for (Parameter param in namedParams) {
1622+
bool isLast = param == namedParams.last;
1623+
builder.write(renderParam(param, isLast ? '' : ', '));
1624+
builder.write(' ');
1625+
}
1626+
1627+
// suffix
16061628
if (namedParams.isNotEmpty) {
1607-
fragments.add(renderParams(namedParams, open: '{', close: '}'));
1629+
builder.write('}');
1630+
} else if (positionalParams.isNotEmpty) {
1631+
builder.write(']');
16081632
}
16091633

1610-
return fragments.join(separator);
1634+
return builder.toString().trim();
16111635
}
16121636

16131637
@override

‎test/model_test.dart

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1461,6 +1461,12 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
14611461
expect(params.contains('List') && params.contains('Apple'), isTrue);
14621462
});
14631463

1464+
test('commas on same param line', () {
1465+
ModelFunction method = fakeLibrary.functions.firstWhere((f) => f.name == 'paintImage1');
1466+
String params = method.linkedParams();
1467+
expect(params, contains(', </span>'));
1468+
});
1469+
14641470
test('param exported in library', () {
14651471
var param = paramFromExportLib.parameters[0];
14661472
expect(param.name, equals('helper'));

‎testing/test_package/lib/fake.dart

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -440,3 +440,30 @@ typedef int Callback2(String);
440440

441441
/// Adds another callback.
442442
void addCallback2(Callback2 callback) { }
443+
444+
const required = 'required';
445+
446+
/// Paints an image into the given rectangle in the canvas.
447+
void paintImage1({
448+
@required String canvas,
449+
@required int rect,
450+
@required ExtraSpecialList image,
451+
BaseForDocComments colorFilter,
452+
String repeat: LongFirstLine.THING
453+
}) {
454+
// nothing to do here -
455+
456+
}
457+
458+
/// Paints an image into the given rectangle in the canvas.
459+
void paintImage2(
460+
String fooParam, [
461+
@required String canvas,
462+
@required int rect,
463+
@required ExtraSpecialList image,
464+
BaseForDocComments colorFilter,
465+
String repeat = LongFirstLine.THING
466+
]) {
467+
// nothing to do here -
468+
469+
}

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -283,7 +283,7 @@ <h2>Operators</h2>
283283
<h2>Methods</h2>
284284
<dl class="callables">
285285
<dt id="isGreaterThan" class="callable">
286-
<span class="name"><a href="ex/Apple/isGreaterThan.html">isGreaterThan</a></span><span class="signature">(<wbr><span class="parameter" id="isGreaterThan-param-number"><span class="type-annotation">int</span> <span class="parameter-name">number</span></span>, {<span class="parameter" id="isGreaterThan-param-check"><span class="type-annotation">int</span> <span class="parameter-name">check</span>: <span class="default-value">5</span></span>})
286+
<span class="name"><a href="ex/Apple/isGreaterThan.html">isGreaterThan</a></span><span class="signature">(<wbr><span class="parameter" id="isGreaterThan-param-number"><span class="type-annotation">int</span> <span class="parameter-name">number</span>, {</span> <span class="parameter" id="isGreaterThan-param-check"><span class="type-annotation">int</span> <span class="parameter-name">check</span>: <span class="default-value">5</span></span> })
287287
<span class="returntype parameter">&#8594; bool</span>
288288
</span>
289289
</dt>
@@ -324,7 +324,7 @@ <h2>Methods</h2>
324324
<p></p>
325325
</dd>
326326
<dt id="printMsg" class="callable">
327-
<span class="name"><a href="ex/Apple/printMsg.html">printMsg</a></span><span class="signature">(<wbr><span class="parameter" id="printMsg-param-msg"><span class="type-annotation">String</span> <span class="parameter-name">msg</span></span>, [<span class="parameter" id="printMsg-param-linebreak"><span class="type-annotation">bool</span> <span class="parameter-name">linebreak</span></span>])
327+
<span class="name"><a href="ex/Apple/printMsg.html">printMsg</a></span><span class="signature">(<wbr><span class="parameter" id="printMsg-param-msg"><span class="type-annotation">String</span> <span class="parameter-name">msg</span>, [</span> <span class="parameter" id="printMsg-param-linebreak"><span class="type-annotation">bool</span> <span class="parameter-name">linebreak</span></span> ])
328328
<span class="returntype parameter">&#8594; void</span>
329329
</span>
330330
</dt>

‎testing/test_package_docs/ex/Apple/isGreaterThan.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ <h5><a href="ex/Apple-class.html">Apple</a></h5>
111111
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
112112
<section class="multi-line-signature">
113113
<span class="returntype">bool</span>
114-
<span class="name ">isGreaterThan</span>(<wbr><span class="parameter" id="isGreaterThan-param-number"><span class="type-annotation">int</span> <span class="parameter-name">number</span></span>, {<span class="parameter" id="isGreaterThan-param-check"><span class="type-annotation">int</span> <span class="parameter-name">check</span>: <span class="default-value">5</span></span>})
114+
<span class="name ">isGreaterThan</span>(<wbr><span class="parameter" id="isGreaterThan-param-number"><span class="type-annotation">int</span> <span class="parameter-name">number</span>, {</span> <span class="parameter" id="isGreaterThan-param-check"><span class="type-annotation">int</span> <span class="parameter-name">check</span>: <span class="default-value">5</span></span> })
115115
</section>
116116

117117

‎testing/test_package_docs/ex/Apple/printMsg.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ <h5><a href="ex/Apple-class.html">Apple</a></h5>
111111
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
112112
<section class="multi-line-signature">
113113
<span class="returntype">void</span>
114-
<span class="name ">printMsg</span>(<wbr><span class="parameter" id="printMsg-param-msg"><span class="type-annotation">String</span> <span class="parameter-name">msg</span></span>, [<span class="parameter" id="printMsg-param-linebreak"><span class="type-annotation">bool</span> <span class="parameter-name">linebreak</span></span>])
114+
<span class="name ">printMsg</span>(<wbr><span class="parameter" id="printMsg-param-msg"><span class="type-annotation">String</span> <span class="parameter-name">msg</span>, [</span> <span class="parameter" id="printMsg-param-linebreak"><span class="type-annotation">bool</span> <span class="parameter-name">linebreak</span></span> ])
115115
</section>
116116

117117

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -297,7 +297,7 @@ <h2>Methods</h2>
297297
<p></p>
298298
</dd>
299299
<dt id="isGreaterThan" class="callable inherited">
300-
<span class="name"><a href="ex/Apple/isGreaterThan.html">isGreaterThan</a></span><span class="signature">(<wbr><span class="parameter" id="isGreaterThan-param-number"><span class="type-annotation">int</span> <span class="parameter-name">number</span></span>, {<span class="parameter" id="isGreaterThan-param-check"><span class="type-annotation">int</span> <span class="parameter-name">check</span>: <span class="default-value">5</span></span>})
300+
<span class="name"><a href="ex/Apple/isGreaterThan.html">isGreaterThan</a></span><span class="signature">(<wbr><span class="parameter" id="isGreaterThan-param-number"><span class="type-annotation">int</span> <span class="parameter-name">number</span>, {</span> <span class="parameter" id="isGreaterThan-param-check"><span class="type-annotation">int</span> <span class="parameter-name">check</span>: <span class="default-value">5</span></span> })
301301
<span class="returntype parameter">&#8594; bool</span>
302302
</span>
303303
</dt>
@@ -341,7 +341,7 @@ <h2>Methods</h2>
341341
<div class="features">inherited</div>
342342
</dd>
343343
<dt id="printMsg" class="callable inherited">
344-
<span class="name"><a href="ex/Apple/printMsg.html">printMsg</a></span><span class="signature">(<wbr><span class="parameter" id="printMsg-param-msg"><span class="type-annotation">String</span> <span class="parameter-name">msg</span></span>, [<span class="parameter" id="printMsg-param-linebreak"><span class="type-annotation">bool</span> <span class="parameter-name">linebreak</span></span>])
344+
<span class="name"><a href="ex/Apple/printMsg.html">printMsg</a></span><span class="signature">(<wbr><span class="parameter" id="printMsg-param-msg"><span class="type-annotation">String</span> <span class="parameter-name">msg</span>, [</span> <span class="parameter" id="printMsg-param-linebreak"><span class="type-annotation">bool</span> <span class="parameter-name">linebreak</span></span> ])
345345
<span class="returntype parameter">&#8594; void</span>
346346
</span>
347347
</dt>
@@ -359,7 +359,7 @@ <h2>Methods</h2>
359359
<div class="features">inherited</div>
360360
</dd>
361361
<dt id="writeMsg" class="callable">
362-
<span class="name"><a href="ex/B/writeMsg.html">writeMsg</a></span><span class="signature">(<wbr><span class="parameter" id="writeMsg-param-msg"><span class="type-annotation">String</span> <span class="parameter-name">msg</span></span>, [<span class="parameter" id="writeMsg-param-transformMsg"><span class="type-annotation">String</span> <span class="parameter-name">transformMsg</span>(<span class="parameter" id="transformMsg-param-origMsg"><span class="type-annotation">String</span> <span class="parameter-name">origMsg</span></span>, <span class="parameter" id="transformMsg-param-flag"><span class="type-annotation">bool</span> <span class="parameter-name">flag</span></span>)</span>])
362+
<span class="name"><a href="ex/B/writeMsg.html">writeMsg</a></span><span class="signature">(<wbr><span class="parameter" id="writeMsg-param-msg"><span class="type-annotation">String</span> <span class="parameter-name">msg</span>, [</span> <span class="parameter" id="writeMsg-param-transformMsg"><span class="type-annotation">String</span> <span class="parameter-name">transformMsg</span>(<span class="parameter" id="transformMsg-param-origMsg"><span class="type-annotation">String</span> <span class="parameter-name">origMsg</span>, </span> <span class="parameter" id="transformMsg-param-flag"><span class="type-annotation">bool</span> <span class="parameter-name">flag</span></span>)</span> ])
363363
<span class="returntype parameter">&#8594; void</span>
364364
</span>
365365
</dt>

‎testing/test_package_docs/ex/B/writeMsg.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ <h5><a href="ex/B-class.html">B</a></h5>
112112
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
113113
<section class="multi-line-signature">
114114
<span class="returntype">void</span>
115-
<span class="name ">writeMsg</span>(<wbr><span class="parameter" id="writeMsg-param-msg"><span class="type-annotation">String</span> <span class="parameter-name">msg</span></span>, [<span class="parameter" id="writeMsg-param-transformMsg"><span class="type-annotation">String</span> <span class="parameter-name">transformMsg</span>(<span class="parameter" id="transformMsg-param-origMsg"><span class="type-annotation">String</span> <span class="parameter-name">origMsg</span></span>, <span class="parameter" id="transformMsg-param-flag"><span class="type-annotation">bool</span> <span class="parameter-name">flag</span></span>)</span>])
115+
<span class="name ">writeMsg</span>(<wbr><span class="parameter" id="writeMsg-param-msg"><span class="type-annotation">String</span> <span class="parameter-name">msg</span>, [</span> <span class="parameter" id="writeMsg-param-transformMsg"><span class="type-annotation">String</span> <span class="parameter-name">transformMsg</span>(<span class="parameter" id="transformMsg-param-origMsg"><span class="type-annotation">String</span> <span class="parameter-name">origMsg</span>, </span> <span class="parameter" id="transformMsg-param-flag"><span class="type-annotation">bool</span> <span class="parameter-name">flag</span></span>)</span> ])
116116
</section>
117117

118118

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -277,7 +277,7 @@ <h2>Methods</h2>
277277
<div class="features">inherited</div>
278278
</dd>
279279
<dt id="writeAll" class="callable inherited">
280-
<span class="name"><a href="ex/CatString/writeAll.html">writeAll</a></span><span class="signature">(<wbr><span class="parameter" id="writeAll-param-objects"><span class="type-annotation">Iterable</span> <span class="parameter-name">objects</span></span>, [<span class="parameter" id="writeAll-param-separator"><span class="type-annotation">String</span> <span class="parameter-name">separator</span> = <span class="default-value">""</span></span>])
280+
<span class="name"><a href="ex/CatString/writeAll.html">writeAll</a></span><span class="signature">(<wbr><span class="parameter" id="writeAll-param-objects"><span class="type-annotation">Iterable</span> <span class="parameter-name">objects</span>, [</span> <span class="parameter" id="writeAll-param-separator"><span class="type-annotation">String</span> <span class="parameter-name">separator</span> = <span class="default-value">""</span></span> ])
281281
<span class="returntype parameter">&#8594; void</span>
282282
</span>
283283
</dt>
@@ -295,7 +295,7 @@ <h2>Methods</h2>
295295
<div class="features">inherited</div>
296296
</dd>
297297
<dt id="writeln" class="callable inherited">
298-
<span class="name"><a href="ex/CatString/writeln.html">writeln</a></span><span class="signature">(<wbr>[<span class="parameter" id="writeln-param-obj"><span class="type-annotation">Object</span> <span class="parameter-name">obj</span> = <span class="default-value">""</span></span>])
298+
<span class="name"><a href="ex/CatString/writeln.html">writeln</a></span><span class="signature">(<wbr>[<span class="parameter" id="writeln-param-obj"><span class="type-annotation">Object</span> <span class="parameter-name">obj</span> = <span class="default-value">""</span></span> ])
299299
<span class="returntype parameter">&#8594; void</span>
300300
</span>
301301
</dt>

0 commit comments

Comments
 (0)