-
Notifications
You must be signed in to change notification settings - Fork 124
Major refactor of dartdoc "features" and annotations #2600
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.
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
jcollins-g
merged 20 commits into
dart-lang:master
from
jcollins-g:generic-metadata+refactor-feature
Apr 2, 2021
Merged
Changes from all commits
Commits
Show all changes
20 commits
Select commit
Hold shift + click to select a range
ecdf57f
beginning
jcollins-g 5b22cd6
Merge branch 'master' into generic-metadata
jcollins-g f97ad5b
Merge branch 'master' into generic-metadata
jcollins-g eb67fc0
first test
jcollins-g 125db39
test
jcollins-g dd354f5
begin extracting annotation
jcollins-g dbbe68d
dartfmt, comment
jcollins-g c7f64f6
Update skip
jcollins-g ee347a9
Merge branch 'master' into generic-metadata
jcollins-g d135ed4
Rebuild renderers
jcollins-g 8ac15c7
Beginning feature refactor
jcollins-g 1c35db9
Getting there
jcollins-g 065ab93
obliterate strings
jcollins-g c4eac77
Final cleanups
jcollins-g d5ba425
Bypass @Native crashing us in flutter
jcollins-g 4a295ef
Restrict ast import
jcollins-g 6af13c4
Expand feature rendering out and get span classes fixed in parameters
jcollins-g 525a9fa
dartfmt
jcollins-g 06066db
Merge branch 'master' into generic-metadata+refactor-feature
jcollins-g 77dafb7
review comments
jcollins-g File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| // Copyright (c) 2021, the Dart project authors. Please see the AUTHORS file | ||
| // for details. All rights reserved. Use of this source code is governed by a | ||
| // BSD-style license that can be found in the LICENSE file. | ||
|
|
||
| import 'package:analyzer/dart/element/element.dart'; | ||
| import 'package:dartdoc/src/element_type.dart'; | ||
| import 'package:dartdoc/src/model/feature.dart'; | ||
| import 'package:dartdoc/src/model/getter_setter_combo.dart'; | ||
| import 'package:dartdoc/src/model/library.dart'; | ||
| import 'package:dartdoc/src/model/model_element.dart'; | ||
| import 'package:dartdoc/src/model/package_graph.dart'; | ||
|
|
||
| /// Represents a Dart annotation, attached to an element in the source code with | ||
| /// `@`. | ||
| class Annotation extends Feature { | ||
| final ElementAnnotation annotation; | ||
| final Library library; | ||
| final PackageGraph packageGraph; | ||
|
|
||
| Annotation(this.annotation, this.library, this.packageGraph) | ||
| : super(annotation.element.name); | ||
|
|
||
| String _linkedNameWithParameters; | ||
| @override | ||
| String get linkedNameWithParameters => _linkedNameWithParameters ??= | ||
| packageGraph.rendererFactory.featureRenderer.renderAnnotation(this); | ||
|
|
||
| /// Return the linked name of the annotation. | ||
| @override | ||
| String get linkedName => annotation.element is PropertyAccessorElement | ||
| ? ModelElement.fromElement(annotation.element, packageGraph).linkedName | ||
| // TODO(jcollins-g): consider linking to constructor instead of type? | ||
| : modelType.linkedName; | ||
|
|
||
| ElementType _modelType; | ||
| ElementType get modelType { | ||
| if (_modelType == null) { | ||
| var annotatedWith = annotation.element; | ||
| if (annotatedWith is ConstructorElement) { | ||
| _modelType = | ||
| ElementType.from(annotatedWith.returnType, library, packageGraph); | ||
| } else if (annotatedWith is PropertyAccessorElement) { | ||
| _modelType = | ||
| (ModelElement.fromElement(annotatedWith.variable, packageGraph) | ||
| as GetterSetterCombo) | ||
| .modelType; | ||
| } else { | ||
| assert(false, | ||
| 'non-callable element used as annotation?: ${annotation.element}'); | ||
| } | ||
| } | ||
| return _modelType; | ||
| } | ||
|
|
||
| String _parameterText; | ||
| String get parameterText { | ||
| // TODO(srawlins): Attempt to revive constructor arguments in an annotation, | ||
| // akin to source_gen's Reviver, in order to link to inner components. For | ||
| // example, in `@Foo(const Bar(), baz: <Baz>[Baz.one, Baz.two])`, link to | ||
| // `Foo`, `Bar`, `Baz`, `Baz.one`, and `Baz.two`. | ||
| if (_parameterText == null) { | ||
| var source = annotation.toSource(); | ||
| var startIndex = source.indexOf('('); | ||
| _parameterText = | ||
| source.substring(startIndex == -1 ? source.length : startIndex); | ||
| } | ||
| return _parameterText; | ||
| } | ||
|
|
||
| @override | ||
| bool get isPublic => | ||
| modelType.isPublic && | ||
| modelType is DefinedElementType && | ||
| !packageGraph.invisibleAnnotations | ||
| .contains((modelType as DefinedElementType).element); | ||
|
|
||
| @override | ||
| bool operator ==(Object other) { | ||
| if (other is Annotation) { | ||
| return other.annotation == annotation; | ||
| } | ||
| return false; | ||
| } | ||
|
|
||
| @override | ||
| int get hashCode => annotation.hashCode; | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| // Copyright (c) 2021, the Dart project authors. Please see the AUTHORS file | ||
| // for details. All rights reserved. Use of this source code is governed by a | ||
| // BSD-style license that can be found in the LICENSE file. | ||
|
|
||
| import 'package:collection/collection.dart'; | ||
| import 'package:dartdoc/src/model/privacy.dart'; | ||
|
|
||
| int byFeatureOrdering(Feature a, Feature b) { | ||
| if (a.sortGroup < b.sortGroup) return -1; | ||
| if (a.sortGroup > b.sortGroup) return 1; | ||
| return compareAsciiLowerCaseNatural(a.name, b.name); | ||
| } | ||
|
|
||
| class ElementFeatureNotFoundError extends Error { | ||
| final String message; | ||
|
|
||
| ElementFeatureNotFoundError([this.message]); | ||
|
|
||
| @override | ||
| String toString() => 'ElementFeatureNotFoundError: $message'; | ||
| } | ||
|
|
||
| /// A "feature" includes both explicit annotations in code (e.g. `deprecated`) | ||
| /// as well as others added by the documentation system (`read-write`); | ||
| class Feature implements Privacy { | ||
| final String _name; | ||
|
|
||
| /// Do not use this except in subclasses, prefer const members of this | ||
| /// class instead. | ||
| const Feature(this._name, [this.sortGroup = 0]); | ||
|
|
||
| final String featurePrefix = ''; | ||
|
|
||
| String get name => _name; | ||
|
|
||
| String get linkedName => name; | ||
|
|
||
| String get linkedNameWithParameters => linkedName; | ||
|
|
||
| @override | ||
| bool get isPublic => !name.startsWith('_'); | ||
|
|
||
| /// Numerical sort group for this feature. | ||
| /// Less than zero will sort before custom annotations. | ||
| /// Above zero will sort after custom annotations. | ||
| /// Zero will sort alphabetically among custom annotations. | ||
| // TODO(jcollins-g): consider [Comparable]? | ||
| final int sortGroup; | ||
|
|
||
| static const readOnly = Feature('read-only', 1); | ||
| static const finalFeature = Feature('final', 2); | ||
| static const writeOnly = Feature('write-only', 2); | ||
| static const readWrite = Feature('read / write', 2); | ||
| static const covariant = Feature('covariant', 2); | ||
| static const extended = Feature('extended', 3); | ||
| static const inherited = Feature('inherited', 3); | ||
| static const inheritedGetter = Feature('inherited-getter', 3); | ||
| static const inheritedSetter = Feature('inherited-setter', 3); | ||
| static const lateFeature = Feature('late', 3); | ||
| static const overrideFeature = Feature('override', 3); | ||
| static const overrideGetter = Feature('override-getter', 3); | ||
| static const overrideSetter = Feature('override-setter', 3); | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Haha I had this exact same idea. Excellent.