Skip to content

documentationComment can now be non-nullable #2819

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
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
c867d5f
Straight move
jcollins-g Sep 28, 2021
08b4b6c
Partial
jcollins-g Sep 29, 2021
0a975cd
delete experiment
jcollins-g Sep 29, 2021
61696c7
rebuild
jcollins-g Sep 29, 2021
eec7326
moved computeDocumentationComment and documentationComment
jcollins-g Sep 29, 2021
8a1b94c
Move more documentation comment handling
jcollins-g Sep 30, 2021
41e1fde
remove ??= from a cut and paste
jcollins-g Sep 30, 2021
c5d45a2
Merge branch 'export-to-DocumentationComment' into export-to-Document…
jcollins-g Sep 30, 2021
fc1c37b
Documentation comment move for combos
jcollins-g Sep 30, 2021
c2ed860
Merge branch 'master' into export-to-DocumentationComment
jcollins-g Sep 30, 2021
a5dc81d
Merge branch 'export-to-DocumentationComment' into export-to-Document…
jcollins-g Sep 30, 2021
97628db
better as a getter
jcollins-g Sep 30, 2021
f64ba52
Untangle synthetic combo documentation in preparing for non-null
jcollins-g Sep 30, 2021
668b927
Merge branch 'master' into export-to-DocumentationComment+movemore
jcollins-g Sep 30, 2021
e3f9cc1
Merge branch 'export-to-DocumentationComment+movemore' into export-to…
jcollins-g Sep 30, 2021
a8f252d
rebuild
jcollins-g Sep 30, 2021
a913baf
documentationComment can be made non-nullable
jcollins-g Sep 30, 2021
fb2e28f
Update test.yaml to delete sdk check from beta branch
jcollins-g Sep 30, 2021
91ea1d5
tab conversion error
jcollins-g Oct 1, 2021
f68a999
correct name
jcollins-g Oct 1, 2021
3144c2a
Merge branch 'master' into export-to-DocumentationComment+movemore+no…
jcollins-g Oct 1, 2021
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
3 changes: 3 additions & 0 deletions .github/workflows/test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ jobs:
job: flutter
- sdk: beta
job: sdk-analyzer
# TODO(jcollins-g): Delete exception as 2.15 beta 2 gets underway
- sdk: beta
job: sdk-docs

steps:
- name: Store date
Expand Down
30 changes: 30 additions & 0 deletions lib/src/generator/templates.runtime_renderers.dart
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,13 @@ class _Renderer_Accessor extends RendererBase<Accessor> {
parent: r);
},
),
'hasDocumentationComment': Property(
getValue: (CT_ c) => c.hasDocumentationComment,
renderVariable: (CT_ c, Property<CT_> self,
List<String> remainingNames) =>
self.renderSimpleVariable(c, remainingNames, 'bool'),
getBool: (CT_ c) => c.hasDocumentationComment == true,
),
'href': Property(
getValue: (CT_ c) => c.href,
renderVariable:
Expand Down Expand Up @@ -4018,6 +4025,13 @@ class _Renderer_DocumentationComment
parent: r);
},
),
'hasDocumentationComment': Property(
getValue: (CT_ c) => c.hasDocumentationComment,
renderVariable: (CT_ c, Property<CT_> self,
List<String> remainingNames) =>
self.renderSimpleVariable(c, remainingNames, 'bool'),
getBool: (CT_ c) => c.hasDocumentationComment == true,
),
'hasNodoc': Property(
getValue: (CT_ c) => c.hasNodoc,
renderVariable: (CT_ c, Property<CT_> self,
Expand Down Expand Up @@ -6003,6 +6017,13 @@ class _Renderer_GetterSetterCombo extends RendererBase<GetterSetterCombo> {
self.renderSimpleVariable(c, remainingNames, 'bool'),
getBool: (CT_ c) => c.hasAccessorsWithDocs == true,
),
'hasDocumentationComment': Property(
getValue: (CT_ c) => c.hasDocumentationComment,
renderVariable: (CT_ c, Property<CT_> self,
List<String> remainingNames) =>
self.renderSimpleVariable(c, remainingNames, 'bool'),
getBool: (CT_ c) => c.hasDocumentationComment == true,
),
'hasExplicitGetter': Property(
getValue: (CT_ c) => c.hasExplicitGetter,
renderVariable: (CT_ c, Property<CT_> self,
Expand Down Expand Up @@ -9720,6 +9741,13 @@ class _Renderer_ModelElement extends RendererBase<ModelElement> {
self.renderSimpleVariable(c, remainingNames, 'bool'),
getBool: (CT_ c) => c.hasDocumentation == true,
),
'hasDocumentationComment': Property(
getValue: (CT_ c) => c.hasDocumentationComment,
renderVariable: (CT_ c, Property<CT_> self,
List<String> remainingNames) =>
self.renderSimpleVariable(c, remainingNames, 'bool'),
getBool: (CT_ c) => c.hasDocumentationComment == true,
),
'hasExtendedDocumentation': Property(
getValue: (CT_ c) => c.hasExtendedDocumentation,
renderVariable: (CT_ c, Property<CT_> self,
Expand Down Expand Up @@ -15224,6 +15252,7 @@ const _invisibleGetters = {
'documentationAsHtml',
'elementDocumentation',
'documentationComment',
'hasDocumentationComment',
'hasNodoc',
'sourceFileName',
'fullyQualifiedNameWithoutLibrary',
Expand Down Expand Up @@ -15441,6 +15470,7 @@ const _invisibleGetters = {
'getterSetterBothAvailable',
'oneLineDoc',
'documentationComment',
'hasDocumentationComment',
'modelType',
'isCallable',
'hasParameters',
Expand Down
51 changes: 39 additions & 12 deletions lib/src/model/accessor.dart
Original file line number Diff line number Diff line change
Expand Up @@ -80,22 +80,49 @@ class Accessor extends ModelElement implements EnclosedElement {
: _documentationComment ??= () {
_documentationCommentComputed = true;
if (isSynthetic) {
// If we're a setter, only display something if we have something different than the getter.
// TODO(jcollins-g): modify analyzer to do this itself?
if (isGetter ||
definingCombo.hasNodoc ||
(isSetter &&
definingCombo.hasGetter &&
definingCombo.getter.documentationComment !=
definingCombo.documentationComment)) {
return stripComments(definingCombo.documentationComment);
} else {
return '';
}
return _syntheticDocumentationComment;
}
return stripComments(super.documentationComment);
}();

String /*!*/ __syntheticDocumentationComment;

/// Build a documentation comment for this accessor assuming it is synthetic.
/// Value here is not useful if [isSynthetic] is false.
String /*!*/ get _syntheticDocumentationComment =>
__syntheticDocumentationComment ??= () {
if (_hasSyntheticDocumentationComment) {
return definingCombo.documentationComment ?? '';
}
return '';
}();

/// If this is a getter, assume we want synthetic documentation.
/// If the definingCombo has a nodoc tag, we want synthetic documentation
/// for a synthetic accessor just in case it is inherited somewhere
/// down the line due to split inheritance.
bool get _hasSyntheticDocumentationComment =>
(isGetter || definingCombo.hasNodoc || _comboDocsAreIndependent()) &&
definingCombo.hasDocumentationComment;

// If we're a setter, and a getter exists, do not add synthetic
// documentation if the combo's documentation is actually derived
// from that getter.
bool _comboDocsAreIndependent() {
if (isSetter && definingCombo.hasGetter) {
if (definingCombo.getter.isSynthetic ||
!definingCombo.documentationFrom.contains(this)) {
return true;
}
}
return false;
}

@override
bool get hasDocumentationComment => isSynthetic
? _hasSyntheticDocumentationComment
: element.documentationComment != null;

@override
void warn(PackageWarning kind,
{String message,
Expand Down
10 changes: 7 additions & 3 deletions lib/src/model/documentation_comment.dart
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ mixin DocumentationComment
@override
List<DocumentationComment> get documentationFrom =>
_documentationFrom ??= () {
if (documentationComment == null &&
if (!hasDocumentationComment &&
this is Inheritable &&
(this as Inheritable).overriddenElement != null) {
return (this as Inheritable).overriddenElement.documentationFrom;
Expand Down Expand Up @@ -81,11 +81,15 @@ mixin DocumentationComment
return _elementDocumentation;
}

String get documentationComment;
String /*!*/ get documentationComment;

/// True if [this] has a synthetic/inherited or local documentation
/// comment. False otherwise.
bool get hasDocumentationComment;

/// Returns true if the raw documentation comment has a nodoc indication.
bool get hasNodoc {
if (documentationComment != null &&
if (hasDocumentationComment &&
(documentationComment.contains('@nodoc') ||
documentationComment.contains('<nodoc>'))) {
return true;
Expand Down
67 changes: 38 additions & 29 deletions lib/src/model/getter_setter_combo.dart
Original file line number Diff line number Diff line change
Expand Up @@ -161,44 +161,53 @@ mixin GetterSetterCombo on ModelElement {
bool _documentationCommentComputed = false;
String _documentationComment;
@override
String get documentationComment => _documentationCommentComputed
String /*!*/ get documentationComment => _documentationCommentComputed
? _documentationComment
: _documentationComment ??= () {
_documentationCommentComputed = true;
var docs = _getterSetterDocumentationComment;
if (docs.isEmpty) return element.documentationComment;
if (docs.isEmpty) return element.documentationComment ?? '';
return docs;
}();

/// Derive a synthetic documentation comment using the documentation from
String get _getterSetterDocumentationComment {
var buffer = StringBuffer();

// Check for synthetic before public, always, or stack overflow.
if (hasGetter && !getter.isSynthetic && getter.isPublic) {
assert(getter.documentationFrom.length == 1);
// We have to check against dropTextFrom here since documentationFrom
// doesn't yield the real elements for GetterSetterCombos.
if (!config.dropTextFrom
.contains(getter.documentationFrom.first.element.library.name)) {
var docs = getter.documentationFrom.first.documentationComment;
if (docs != null) buffer.write(docs);
}
}
@override
bool get hasDocumentationComment =>
_getterSetterDocumentationComment.isNotEmpty ||
element.documentationComment != null;

String __getterSetterDocumentationComment;

/// Derive a documentation comment for the combo by copying documentation
/// from the [getter] and/or [setter].
String /*!*/ get _getterSetterDocumentationComment =>
__getterSetterDocumentationComment ??= () {
var buffer = StringBuffer();

if (hasSetter && !setter.isSynthetic && setter.isPublic) {
assert(setter.documentationFrom.length == 1);
if (!config.dropTextFrom
.contains(setter.documentationFrom.first.element.library.name)) {
var docs = setter.documentationFrom.first.documentationComment;
if (docs != null) {
if (buffer.isNotEmpty) buffer.write('\n\n');
buffer.write(docs);
// Check for synthetic before public, always, or stack overflow.
if (hasGetter && !getter.isSynthetic && getter.isPublic) {
assert(getter.documentationFrom.length == 1);
var fromGetter = getter.documentationFrom.first;
// We have to check against dropTextFrom here since documentationFrom
// doesn't yield the real elements for GetterSetterCombos.
if (!config.dropTextFrom.contains(fromGetter.element.library.name)) {
if (fromGetter.hasDocumentationComment) {
buffer.write(fromGetter.documentationComment);
}
}
}
}
}
return buffer.toString();
}

if (hasSetter && !setter.isSynthetic && setter.isPublic) {
assert(setter.documentationFrom.length == 1);
var fromSetter = setter.documentationFrom.first;
if (!config.dropTextFrom.contains(fromSetter.element.library.name)) {
if (fromSetter.hasDocumentationComment) {
if (buffer.isNotEmpty) buffer.write('\n\n');
buffer.write(fromSetter.documentationComment);
}
}
}
return buffer.toString();
}();

ElementType get modelType {
if (hasGetter) return getter.modelType.returnType;
Expand Down
5 changes: 4 additions & 1 deletion lib/src/model/model_element.dart
Original file line number Diff line number Diff line change
Expand Up @@ -917,7 +917,10 @@ abstract class ModelElement extends Canonicalization
}

@override
String get documentationComment => element.documentationComment;
String /*!*/ get documentationComment => element.documentationComment ?? '';

@override
bool get hasDocumentationComment => element.documentationComment != null;

String _sourceCode;
@override
Expand Down
2 changes: 1 addition & 1 deletion lib/src/model/package_graph.dart
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ class PackageGraph with CommentReferable, Nameable {

Iterable<Future<void>> precacheOneElement(ModelElement m) sync* {
for (var d
in m.documentationFrom.where((d) => d.documentationComment != null)) {
in m.documentationFrom.where((d) => d.hasDocumentationComment)) {
if (d.needsPrecache && !precachedElements.contains(d)) {
precachedElements.add(d);
yield d.precacheLocalDocs();
Expand Down
2 changes: 1 addition & 1 deletion test/end2end/model_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -630,7 +630,7 @@ void main() {
() {
// Verify setup of the test is correct.
expect(invokeToolParentDoc.isCanonical, isTrue);
expect(invokeToolParentDoc.documentationComment, isNull);
expect(invokeToolParentDoc.hasDocumentationComment, isFalse);
// Error message here might look strange due to toString() on Methods, but if this
// fails that means we don't have the correct invokeToolParentDoc instance.
expect(invokeToolParentDoc.documentationFrom,
Expand Down