Skip to content

Fix navigation and constructor docs to include class generics #1556

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Dec 4, 2017
Merged

Fix navigation and constructor docs to include class generics #1556

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5dd4a9a
Add type parameters for constructors
jcollins-g Dec 1, 2017
b10167c
And make navigation consistently include generic types in the class.
jcollins-g Dec 1, 2017
08179e8
Merge branch 'master' of github.com:dart-lang/dartdoc into fix-generi…
jcollins-g Dec 4, 2017
b4f30a5
Update test package docs post-merge
jcollins-g Dec 4, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions lib/src/html/template_data.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,13 @@ abstract class TemplateData<T extends Documentable> {
String get kind => self is ModelElement ? (self as ModelElement).kind : null;

List get navLinks;
Documentable get parent => navLinks.isNotEmpty ? navLinks.last : null;
List get navLinksWithGenerics => [];
Documentable get parent {
if (navLinksWithGenerics.isEmpty) {
return navLinks.isNotEmpty ? navLinks.last : null;
}
return navLinksWithGenerics.last;
}

bool get includeVersion => false;

Expand Down Expand Up @@ -236,7 +242,9 @@ class ConstructorTemplateData extends TemplateData<Constructor> {
String get layoutTitle => _layoutTitle(
constructor.name, constructor.fullKind, constructor.isDeprecated);
@override
List get navLinks => [package, library, clazz];
List get navLinks => [package, library];
@override
List get navLinksWithGenerics => [clazz];
@override
Iterable<Subnav> getSubNavItems() => _gatherSubnavForInvokable(constructor);
@override
Expand Down Expand Up @@ -331,7 +339,9 @@ class MethodTemplateData extends TemplateData<Method> {
'API docs for the ${method.name} method from the ${clazz.name} class, '
'for the Dart programming language.';
@override
List get navLinks => [package, library, clazz];
List get navLinks => [package, library];
@override
List get navLinksWithGenerics => [clazz];
@override
Iterable<Subnav> getSubNavItems() => _gatherSubnavForInvokable(method);
@override
Expand Down Expand Up @@ -361,7 +371,9 @@ class PropertyTemplateData extends TemplateData<Field> {
'API docs for the ${property.name} $type from the ${clazz.name} class, '
'for the Dart programming language.';
@override
List get navLinks => [package, library, clazz];
List get navLinks => [package, library];
@override
List get navLinksWithGenerics => [clazz];
@override
String get htmlBase => '../..';

Expand Down
22 changes: 19 additions & 3 deletions lib/src/model.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1126,11 +1126,15 @@ class Class extends ModelElement
}

class Constructor extends ModelElement
with SourceCodeMixin
with SourceCodeMixin, TypeParameters
implements EnclosedElement {
Constructor(ConstructorElement element, Library library)
: super(element, library, null);

@override
// TODO(jcollins-g): Revisit this when dart-lang/sdk#31517 is implemented.
List<TypeParameter> get typeParameters => (enclosingElement as Class).typeParameters;

@override
ModelElement get enclosingElement =>
new ModelElement.from(_constructor.enclosingElement, library);
Expand Down Expand Up @@ -1172,6 +1176,20 @@ class Constructor extends ModelElement
return _name;
}

String _nameWithGenerics;
@override
String get nameWithGenerics {
if (_nameWithGenerics == null) {
String constructorName = element.name;
if (constructorName.isEmpty) {
_nameWithGenerics = '${enclosingElement.name}${genericParameters}';
} else {
_nameWithGenerics = '${enclosingElement.name}${genericParameters}.$constructorName';
}
}
return _nameWithGenerics;
}

String get shortName {
if (name.contains('.')) {
return name.substring(_constructor.enclosingElement.name.length + 1);
Expand Down Expand Up @@ -4689,8 +4707,6 @@ abstract class SourceCodeMixin {
}

abstract class TypeParameters implements Nameable {
Element get element;

String get nameWithGenerics => '$name$genericParameters';

String get genericParameters {
Expand Down
3 changes: 3 additions & 0 deletions lib/templates/_head.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@
{{#navLinks}}
<li><a href="{{href}}">{{name}}</a></li>
{{/navLinks}}
{{#navLinksWithGenerics}}
<li><a href="{{href}}">{{name}}{{{genericParameters}}}</a></li>
{{/navLinksWithGenerics}}
{{^hasHomepage}}
<li class="self-crumb">{{{ layoutTitle }}}</li>
{{/hasHomepage}}
Expand Down
11 changes: 10 additions & 1 deletion lib/templates/constructor.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,17 @@ <h5>{{parent.kind}} {{parent.name}}</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
{{#constructor}}
<section class="multi-line-signature">
{{#hasAnnotations}}
<div>
<ol class="annotation-list">
{{#annotations}}
<li>{{{.}}}</li>
{{/annotations}}
</ol>
</div>
{{/hasAnnotations}}
{{#isConst}}const{{/isConst}}
{{>name_summary}}(<wbr>{{#hasParameters}}{{{linkedParamsLines}}}{{/hasParameters}})
<span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{{nameWithGenerics}}}</span>(<wbr>{{#hasParameters}}{{{linkedParamsLines}}}{{/hasParameters}})
</section>

{{>documentation}}
Expand Down
13 changes: 12 additions & 1 deletion test/model_test.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1915,15 +1915,26 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
group('Constructor', () {
Constructor appleDefaultConstructor, constCatConstructor;
Constructor appleConstructorFromString;
Class apple, constCat;
Constructor constructorTesterDefault, constructorTesterFromSomething;
Class apple, constCat, constructorTester;
setUp(() {
apple = exLibrary.classes.firstWhere((c) => c.name == 'Apple');
constCat = exLibrary.classes.firstWhere((c) => c.name == 'ConstantCat');
constructorTester = fakeLibrary.classes.firstWhere((c) => c.name == 'ConstructorTester');
constCatConstructor = constCat.constructors[0];
appleDefaultConstructor =
apple.constructors.firstWhere((c) => c.name == 'Apple');
appleConstructorFromString =
apple.constructors.firstWhere((c) => c.name == 'Apple.fromString');
constructorTesterDefault =
constructorTester.constructors.firstWhere((c) => c.name == 'ConstructorTester');
constructorTesterFromSomething =
constructorTester.constructors.firstWhere((c) => c.name == 'ConstructorTester.fromSomething');
});

test('displays generic parameters correctly', () {
expect(constructorTesterDefault.nameWithGenerics, 'ConstructorTester&lt;A, B&gt;');
expect(constructorTesterFromSomething.nameWithGenerics, 'ConstructorTester&lt;A, B&gt;.fromSomething');
});

test('has a fully qualified name', () {
Expand Down
5 changes: 5 additions & 0 deletions testing/test_package/lib/fake.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,11 @@ abstract class BaseThingy2 implements BaseThingy {
ImplementingThingy2 get aImplementingThingy;
}

class ConstructorTester<A, B> {
ConstructorTester(String param1) {}
ConstructorTester.fromSomething(A foo) {}
}

class HasGenerics<X, Y, Z> {
HasGenerics(X x, Y y, Z z) {}

Expand Down
4 changes: 2 additions & 2 deletions testing/test_package_docs/ex/AnotherParameterizedClass/AnotherParameterizedClass.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<ol class="breadcrumbs gt-separated dark hidden-xs">
<li><a href="index.html">test_package</a></li>
<li><a href="ex/ex-library.html">ex</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass&lt;B&gt;</a></li>
<li class="self-crumb">constructor AnotherParameterizedClass</li>
</ol>
<div class="self-name">AnotherParameterizedClass</div>
Expand Down Expand Up @@ -63,7 +63,7 @@ <h5>class AnotherParameterizedClass</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">AnotherParameterizedClass</span>(<wbr>)
<span class="name ">AnotherParameterizedClass&lt;B&gt;</span>(<wbr>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/AnotherParameterizedClass/hashCode.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<ol class="breadcrumbs gt-separated dark hidden-xs">
<li><a href="index.html">test_package</a></li>
<li><a href="ex/ex-library.html">ex</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass&lt;B&gt;</a></li>
<li class="self-crumb">property hashCode</li>
</ol>
<div class="self-name">hashCode</div>
Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/AnotherParameterizedClass/noSuchMethod.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<ol class="breadcrumbs gt-separated dark hidden-xs">
<li><a href="index.html">test_package</a></li>
<li><a href="ex/ex-library.html">ex</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass&lt;B&gt;</a></li>
<li class="self-crumb">method noSuchMethod</li>
</ol>
<div class="self-name">noSuchMethod</div>
Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/AnotherParameterizedClass/operator_equals.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<ol class="breadcrumbs gt-separated dark hidden-xs">
<li><a href="index.html">test_package</a></li>
<li><a href="ex/ex-library.html">ex</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass&lt;B&gt;</a></li>
<li class="self-crumb">method operator ==</li>
</ol>
<div class="self-name">operator ==</div>
Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/AnotherParameterizedClass/runtimeType.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<ol class="breadcrumbs gt-separated dark hidden-xs">
<li><a href="index.html">test_package</a></li>
<li><a href="ex/ex-library.html">ex</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass&lt;B&gt;</a></li>
<li class="self-crumb">property runtimeType</li>
</ol>
<div class="self-name">runtimeType</div>
Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/AnotherParameterizedClass/toString.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<ol class="breadcrumbs gt-separated dark hidden-xs">
<li><a href="index.html">test_package</a></li>
<li><a href="ex/ex-library.html">ex</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass</a></li>
<li><a href="ex/AnotherParameterizedClass-class.html">AnotherParameterizedClass&lt;B&gt;</a></li>
<li class="self-crumb">method toString</li>
</ol>
<div class="self-name">toString</div>
Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/Apple/Apple.fromString.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ <h5>class Apple</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">Apple.fromString</span>(<wbr><span class="parameter" id="fromString-param-s"><span class="type-annotation">String</span> <span class="parameter-name">s</span></span>)
<span class="name ">Apple.fromString</span>(<wbr><span class="parameter" id="fromString-param-s"><span class="type-annotation">String</span> <span class="parameter-name">s</span></span>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/Apple/Apple.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ <h5>class Apple</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">Apple</span>(<wbr>)
<span class="name ">Apple</span>(<wbr>)
</section>

<section class="desc markdown">
Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/B/B.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ <h5>class B</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">B</span>(<wbr>)
<span class="name ">B</span>(<wbr>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/Cat/Cat.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ <h5>class Cat</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">Cat</span>(<wbr>)
<span class="name ">Cat</span>(<wbr>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/CatString/CatString.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ <h5>class CatString</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">CatString</span>(<wbr>)
<span class="name ">CatString</span>(<wbr>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/ConstantCat/ConstantCat.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ <h5>class ConstantCat</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">
const
<span class="name ">ConstantCat</span>(<wbr><span class="parameter" id="-param-name"><span class="type-annotation">String</span> <span class="parameter-name">name</span></span>)
<span class="name ">ConstantCat</span>(<wbr><span class="parameter" id="-param-name"><span class="type-annotation">String</span> <span class="parameter-name">name</span></span>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/Deprecated/Deprecated.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ <h5>class Deprecated</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">
const
<span class="name ">Deprecated</span>(<wbr><span class="parameter" id="-param-expires"><span class="type-annotation">String</span> <span class="parameter-name">expires</span></span>)
<span class="name ">Deprecated</span>(<wbr><span class="parameter" id="-param-expires"><span class="type-annotation">String</span> <span class="parameter-name">expires</span></span>)
</section>


Expand Down
7 changes: 6 additions & 1 deletion testing/test_package_docs/ex/Dog/Dog.deprecatedCreate.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,13 @@ <h5>class Dog</h5>

<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">
<div>
<ol class="annotation-list">
<li>@deprecated</li>
</ol>
</div>

<span class="name deprecated">Dog.deprecatedCreate</span>(<wbr><span class="parameter" id="deprecatedCreate-param-name"><span class="type-annotation">String</span> <span class="parameter-name">name</span></span>)
<span class="name deprecated">Dog.deprecatedCreate</span>(<wbr><span class="parameter" id="deprecatedCreate-param-name"><span class="type-annotation">String</span> <span class="parameter-name">name</span></span>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/Dog/Dog.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ <h5>class Dog</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">Dog</span>(<wbr>)
<span class="name ">Dog</span>(<wbr>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/E/E.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ <h5>class E</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">E</span>(<wbr>)
<span class="name ">E</span>(<wbr>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/ExtendedShortName/ExtendedShortName.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ <h5>class ExtendedShortName</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">
const
<span class="name ">ExtendedShortName</span>(<wbr><span class="parameter" id="-param-aParameter"><span class="type-annotation">String</span> <span class="parameter-name">aParameter</span></span>)
<span class="name ">ExtendedShortName</span>(<wbr><span class="parameter" id="-param-aParameter"><span class="type-annotation">String</span> <span class="parameter-name">aParameter</span></span>)
</section>


Expand Down
4 changes: 2 additions & 2 deletions testing/test_package_docs/ex/F/F.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<ol class="breadcrumbs gt-separated dark hidden-xs">
<li><a href="index.html">test_package</a></li>
<li><a href="ex/ex-library.html">ex</a></li>
<li><a href="ex/F-class.html">F</a></li>
<li><a href="ex/F-class.html">F&lt;T extends String&gt;</a></li>
<li class="self-crumb">constructor F</li>
</ol>
<div class="self-name">F</div>
Expand Down Expand Up @@ -82,7 +82,7 @@ <h5>class F</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">F</span>(<wbr>)
<span class="name ">F&lt;T extends String&gt;</span>(<wbr>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/F/methodWithGenericParam.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<ol class="breadcrumbs gt-separated dark hidden-xs">
<li><a href="index.html">test_package</a></li>
<li><a href="ex/ex-library.html">ex</a></li>
<li><a href="ex/F-class.html">F</a></li>
<li><a href="ex/F-class.html">F&lt;T extends String&gt;</a></li>
<li class="self-crumb">method methodWithGenericParam</li>
</ol>
<div class="self-name">methodWithGenericParam</div>
Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/F/test.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<ol class="breadcrumbs gt-separated dark hidden-xs">
<li><a href="index.html">test_package</a></li>
<li><a href="ex/ex-library.html">ex</a></li>
<li><a href="ex/F-class.html">F</a></li>
<li><a href="ex/F-class.html">F&lt;T extends String&gt;</a></li>
<li class="self-crumb">method test</li>
</ol>
<div class="self-name">test</div>
Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/ForAnnotation/ForAnnotation.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ <h5>class ForAnnotation</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">
const
<span class="name ">ForAnnotation</span>(<wbr><span class="parameter" id="-param-value"><span class="type-annotation">String</span> <span class="parameter-name">value</span></span>)
<span class="name ">ForAnnotation</span>(<wbr><span class="parameter" id="-param-value"><span class="type-annotation">String</span> <span class="parameter-name">value</span></span>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/HasAnnotation/HasAnnotation.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ <h5>class HasAnnotation</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">HasAnnotation</span>(<wbr>)
<span class="name ">HasAnnotation</span>(<wbr>)
</section>


Expand Down
2 changes: 1 addition & 1 deletion testing/test_package_docs/ex/Helper/Helper.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ <h5>class Helper</h5>
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
<section class="multi-line-signature">

<span class="name ">Helper</span>(<wbr>)
<span class="name ">Helper</span>(<wbr>)
</section>


Expand Down
Loading