From 9c2e2610f141e7603bf6ba36d7b6ca105be33df0 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Mon, 8 Mar 2021 11:09:14 -0800 Subject: [PATCH 1/3] Support References in docs --- lib/src/emitter.dart | 33 +++++++++++++++++++++++++------- lib/src/mixins/dartdoc.dart | 4 ++-- lib/src/specs/class.dart | 4 ++-- lib/src/specs/class.g.dart | 8 ++++---- lib/src/specs/constructor.dart | 4 ++-- lib/src/specs/constructor.g.dart | 8 ++++---- lib/src/specs/enum.dart | 8 ++++---- lib/src/specs/enum.g.dart | 16 ++++++++-------- lib/src/specs/extension.dart | 4 ++-- lib/src/specs/extension.g.dart | 8 ++++---- lib/src/specs/field.dart | 4 ++-- lib/src/specs/field.g.dart | 8 ++++---- lib/src/specs/method.dart | 8 ++++---- lib/src/specs/method.g.dart | 16 ++++++++-------- test/specs/class_test.dart | 22 ++++++++++++++++++++- 15 files changed, 97 insertions(+), 58 deletions(-) diff --git a/lib/src/emitter.dart b/lib/src/emitter.dart index 14093cb..702482a 100644 --- a/lib/src/emitter.dart +++ b/lib/src/emitter.dart @@ -106,7 +106,7 @@ class DartEmitter extends Object @override StringSink visitClass(Class spec, [StringSink output]) { output ??= StringBuffer(); - spec.docs.forEach(output.writeln); + _visitDocs(spec.docs, output); spec.annotations.forEach((a) => visitAnnotation(a, output)); if (spec.abstract) { output.write('abstract '); @@ -153,7 +153,7 @@ class DartEmitter extends Object StringSink visitConstructor(Constructor spec, String clazz, [StringSink output]) { output ??= StringBuffer(); - spec.docs.forEach(output.writeln); + _visitDocs(spec.docs, output); spec.annotations.forEach((a) => visitAnnotation(a, output)); if (spec.external) { output.write('external '); @@ -237,7 +237,7 @@ class DartEmitter extends Object @override StringSink visitExtension(Extension spec, [StringSink output]) { output ??= StringBuffer(); - spec.docs.forEach(output.writeln); + _visitDocs(spec.docs, output); spec.annotations.forEach((a) => visitAnnotation(a, output)); output.write('extension'); @@ -305,7 +305,7 @@ class DartEmitter extends Object @override StringSink visitField(Field spec, [StringSink output]) { output ??= StringBuffer(); - spec.docs.forEach(output.writeln); + _visitDocs(spec.docs, output); spec.annotations.forEach((a) => visitAnnotation(a, output)); if (spec.static) { output.write('static '); @@ -419,7 +419,7 @@ class DartEmitter extends Object @override StringSink visitMethod(Method spec, [StringSink output]) { output ??= StringBuffer(); - spec.docs.forEach(output.writeln); + _visitDocs(spec.docs, output); spec.annotations.forEach((a) => visitAnnotation(a, output)); if (spec.external) { output.write('external '); @@ -512,7 +512,8 @@ class DartEmitter extends Object bool optional = false, bool named = false, }) { - spec.docs.forEach(output.writeln); + output ??= StringBuffer(); + _visitDocs(spec.docs, output); spec.annotations.forEach((a) => visitAnnotation(a, output)); // The `required` keyword must precede the `covariant` keyword. if (spec.required) { @@ -575,7 +576,7 @@ class DartEmitter extends Object @override StringSink visitEnum(Enum spec, [StringSink output]) { output ??= StringBuffer(); - spec.docs.forEach(output.writeln); + _visitDocs(spec.docs, output); spec.annotations.forEach((a) => visitAnnotation(a, output)); output.writeln('enum ${spec.name} {'); spec.values.forEach((v) { @@ -589,6 +590,24 @@ class DartEmitter extends Object output.writeln('}'); return output; } + + StringSink _visitDocs(Iterable docs, [StringSink output]) { + output ??= StringBuffer(); + for (var doc in docs) { + if (doc is Reference) { + output.write('['); + visitReference(doc, output); + output.writeln(']'); + } else if (doc is String) { + output.writeln(doc); + } else { + throw ArgumentError( + "doc is expected to be a String or a Reference, but '$doc' is a " + "'${doc.runtimeType}'"); + } + } + return output; + } } /// Returns `true` if: diff --git a/lib/src/mixins/dartdoc.dart b/lib/src/mixins/dartdoc.dart index ae44bd1..2e59a7e 100644 --- a/lib/src/mixins/dartdoc.dart +++ b/lib/src/mixins/dartdoc.dart @@ -6,10 +6,10 @@ import 'package:built_collection/built_collection.dart'; abstract class HasDartDocs { /// Dart docs. - BuiltList get docs; + BuiltList get docs; } abstract class HasDartDocsBuilder { /// Dart docs. - ListBuilder docs; + ListBuilder docs; } diff --git a/lib/src/specs/class.dart b/lib/src/specs/class.dart index 77175f2..f3abb95 100644 --- a/lib/src/specs/class.dart +++ b/lib/src/specs/class.dart @@ -34,7 +34,7 @@ abstract class Class extends Object BuiltList get annotations; @override - BuiltList get docs; + BuiltList get docs; @nullable Reference get extend; @@ -75,7 +75,7 @@ abstract class ClassBuilder extends Object ListBuilder annotations = ListBuilder(); @override - ListBuilder docs = ListBuilder(); + ListBuilder docs = ListBuilder(); Reference extend; diff --git a/lib/src/specs/class.g.dart b/lib/src/specs/class.g.dart index 916b96b..2210699 100644 --- a/lib/src/specs/class.g.dart +++ b/lib/src/specs/class.g.dart @@ -12,7 +12,7 @@ class _$Class extends Class { @override final BuiltList annotations; @override - final BuiltList docs; + final BuiltList docs; @override final Reference extend; @override @@ -172,13 +172,13 @@ class _$ClassBuilder extends ClassBuilder { } @override - ListBuilder get docs { + ListBuilder get docs { _$this; - return super.docs ??= new ListBuilder(); + return super.docs ??= new ListBuilder(); } @override - set docs(ListBuilder docs) { + set docs(ListBuilder docs) { _$this; super.docs = docs; } diff --git a/lib/src/specs/constructor.dart b/lib/src/specs/constructor.dart index fb9f689..efda549 100644 --- a/lib/src/specs/constructor.dart +++ b/lib/src/specs/constructor.dart @@ -28,7 +28,7 @@ abstract class Constructor extends Object BuiltList get annotations; @override - BuiltList get docs; + BuiltList get docs; /// Optional parameters. BuiltList get optionalParameters; @@ -76,7 +76,7 @@ abstract class ConstructorBuilder extends Object ListBuilder annotations = ListBuilder(); @override - ListBuilder docs = ListBuilder(); + ListBuilder docs = ListBuilder(); /// Optional parameters. ListBuilder optionalParameters = ListBuilder(); diff --git a/lib/src/specs/constructor.g.dart b/lib/src/specs/constructor.g.dart index 0f803d9..342a21e 100644 --- a/lib/src/specs/constructor.g.dart +++ b/lib/src/specs/constructor.g.dart @@ -10,7 +10,7 @@ class _$Constructor extends Constructor { @override final BuiltList annotations; @override - final BuiltList docs; + final BuiltList docs; @override final BuiltList optionalParameters; @override @@ -161,13 +161,13 @@ class _$ConstructorBuilder extends ConstructorBuilder { } @override - ListBuilder get docs { + ListBuilder get docs { _$this; - return super.docs ??= new ListBuilder(); + return super.docs ??= new ListBuilder(); } @override - set docs(ListBuilder docs) { + set docs(ListBuilder docs) { _$this; super.docs = docs; } diff --git a/lib/src/specs/enum.dart b/lib/src/specs/enum.dart index cb50ab1..327c5a1 100644 --- a/lib/src/specs/enum.dart +++ b/lib/src/specs/enum.dart @@ -29,7 +29,7 @@ abstract class Enum extends Object BuiltList get annotations; @override - BuiltList get docs; + BuiltList get docs; @override R accept( @@ -54,7 +54,7 @@ abstract class EnumBuilder extends Object ListBuilder annotations = ListBuilder(); @override - ListBuilder docs = ListBuilder(); + ListBuilder docs = ListBuilder(); } @immutable @@ -71,7 +71,7 @@ abstract class EnumValue extends Object BuiltList get annotations; @override - BuiltList get docs; + BuiltList get docs; } abstract class EnumValueBuilder extends Object @@ -87,5 +87,5 @@ abstract class EnumValueBuilder extends Object ListBuilder annotations = ListBuilder(); @override - ListBuilder docs = ListBuilder(); + ListBuilder docs = ListBuilder(); } diff --git a/lib/src/specs/enum.g.dart b/lib/src/specs/enum.g.dart index 8834ebd..8a17d90 100644 --- a/lib/src/specs/enum.g.dart +++ b/lib/src/specs/enum.g.dart @@ -14,7 +14,7 @@ class _$Enum extends Enum { @override final BuiltList annotations; @override - final BuiltList docs; + final BuiltList docs; factory _$Enum([void Function(EnumBuilder) updates]) => (new EnumBuilder()..update(updates)).build() as _$Enum; @@ -109,13 +109,13 @@ class _$EnumBuilder extends EnumBuilder { } @override - ListBuilder get docs { + ListBuilder get docs { _$this; - return super.docs ??= new ListBuilder(); + return super.docs ??= new ListBuilder(); } @override - set docs(ListBuilder docs) { + set docs(ListBuilder docs) { _$this; super.docs = docs; } @@ -182,7 +182,7 @@ class _$EnumValue extends EnumValue { @override final BuiltList annotations; @override - final BuiltList docs; + final BuiltList docs; factory _$EnumValue([void Function(EnumValueBuilder) updates]) => (new EnumValueBuilder()..update(updates)).build() as _$EnumValue; @@ -259,13 +259,13 @@ class _$EnumValueBuilder extends EnumValueBuilder { } @override - ListBuilder get docs { + ListBuilder get docs { _$this; - return super.docs ??= new ListBuilder(); + return super.docs ??= new ListBuilder(); } @override - set docs(ListBuilder docs) { + set docs(ListBuilder docs) { _$this; super.docs = docs; } diff --git a/lib/src/specs/extension.dart b/lib/src/specs/extension.dart index 9260471..18f411d 100644 --- a/lib/src/specs/extension.dart +++ b/lib/src/specs/extension.dart @@ -31,7 +31,7 @@ abstract class Extension extends Object BuiltList get annotations; @override - BuiltList get docs; + BuiltList get docs; @nullable Reference get on; @@ -65,7 +65,7 @@ abstract class ExtensionBuilder extends Object ListBuilder annotations = ListBuilder(); @override - ListBuilder docs = ListBuilder(); + ListBuilder docs = ListBuilder(); Reference on; diff --git a/lib/src/specs/extension.g.dart b/lib/src/specs/extension.g.dart index befd295..495a8d0 100644 --- a/lib/src/specs/extension.g.dart +++ b/lib/src/specs/extension.g.dart @@ -10,7 +10,7 @@ class _$Extension extends Extension { @override final BuiltList annotations; @override - final BuiltList docs; + final BuiltList docs; @override final Reference on; @override @@ -115,13 +115,13 @@ class _$ExtensionBuilder extends ExtensionBuilder { } @override - ListBuilder get docs { + ListBuilder get docs { _$this; - return super.docs ??= new ListBuilder(); + return super.docs ??= new ListBuilder(); } @override - set docs(ListBuilder docs) { + set docs(ListBuilder docs) { _$this; super.docs = docs; } diff --git a/lib/src/specs/field.dart b/lib/src/specs/field.dart index ddb0d28..33e07c1 100644 --- a/lib/src/specs/field.dart +++ b/lib/src/specs/field.dart @@ -28,7 +28,7 @@ abstract class Field extends Object BuiltList get annotations; @override - BuiltList get docs; + BuiltList get docs; /// Field assignment, if any. @nullable @@ -72,7 +72,7 @@ abstract class FieldBuilder extends Object ListBuilder annotations = ListBuilder(); @override - ListBuilder docs = ListBuilder(); + ListBuilder docs = ListBuilder(); /// Field assignment, if any. Code assignment; diff --git a/lib/src/specs/field.g.dart b/lib/src/specs/field.g.dart index 5dfccd9..9d6e6c8 100644 --- a/lib/src/specs/field.g.dart +++ b/lib/src/specs/field.g.dart @@ -10,7 +10,7 @@ class _$Field extends Field { @override final BuiltList annotations; @override - final BuiltList docs; + final BuiltList docs; @override final Code assignment; @override @@ -115,13 +115,13 @@ class _$FieldBuilder extends FieldBuilder { } @override - ListBuilder get docs { + ListBuilder get docs { _$this; - return super.docs ??= new ListBuilder(); + return super.docs ??= new ListBuilder(); } @override - set docs(ListBuilder docs) { + set docs(ListBuilder docs) { _$this; super.docs = docs; } diff --git a/lib/src/specs/method.dart b/lib/src/specs/method.dart index cd6ae1e..bbe3d90 100644 --- a/lib/src/specs/method.dart +++ b/lib/src/specs/method.dart @@ -39,7 +39,7 @@ abstract class Method extends Object BuiltList get annotations; @override - BuiltList get docs; + BuiltList get docs; @override BuiltList get types; @@ -107,7 +107,7 @@ abstract class MethodBuilder extends Object ListBuilder annotations = ListBuilder(); @override - ListBuilder docs = ListBuilder(); + ListBuilder docs = ListBuilder(); @override ListBuilder types = ListBuilder(); @@ -183,7 +183,7 @@ abstract class Parameter extends Object BuiltList get annotations; @override - BuiltList get docs; + BuiltList get docs; @override BuiltList get types; @@ -231,7 +231,7 @@ abstract class ParameterBuilder extends Object ListBuilder annotations = ListBuilder(); @override - ListBuilder docs = ListBuilder(); + ListBuilder docs = ListBuilder(); @override ListBuilder types = ListBuilder(); diff --git a/lib/src/specs/method.g.dart b/lib/src/specs/method.g.dart index ba721b5..a52060a 100644 --- a/lib/src/specs/method.g.dart +++ b/lib/src/specs/method.g.dart @@ -10,7 +10,7 @@ class _$Method extends Method { @override final BuiltList annotations; @override - final BuiltList docs; + final BuiltList docs; @override final BuiltList types; @override @@ -167,13 +167,13 @@ class _$MethodBuilder extends MethodBuilder { } @override - ListBuilder get docs { + ListBuilder get docs { _$this; - return super.docs ??= new ListBuilder(); + return super.docs ??= new ListBuilder(); } @override - set docs(ListBuilder docs) { + set docs(ListBuilder docs) { _$this; super.docs = docs; } @@ -400,7 +400,7 @@ class _$Parameter extends Parameter { @override final BuiltList annotations; @override - final BuiltList docs; + final BuiltList docs; @override final BuiltList types; @override @@ -577,13 +577,13 @@ class _$ParameterBuilder extends ParameterBuilder { } @override - ListBuilder get docs { + ListBuilder get docs { _$this; - return super.docs ??= new ListBuilder(); + return super.docs ??= new ListBuilder(); } @override - set docs(ListBuilder docs) { + set docs(ListBuilder docs) { _$this; super.docs = docs; } diff --git a/test/specs/class_test.dart b/test/specs/class_test.dart index ebf6777..73aa0c5 100644 --- a/test/specs/class_test.dart +++ b/test/specs/class_test.dart @@ -30,7 +30,7 @@ void main() { ); }); - test('should create a class with documentations', () { + test('should create a class with documentation', () { expect( Class( (b) => b @@ -48,6 +48,26 @@ void main() { ); }); + test('should create a class with documentation with references', () { + expect( + Class( + (b) => b + ..name = 'Foo' + ..docs.addAll( + [ + '/// My favorite class is ', + refer('Queue', 'dart:collection'), + '.', + ], + ), + ), + equalsDart(r''' + /// My favorite class is [Queue]. + class Foo {} + '''), + ); + }); + test('should create a class with annotations', () { expect( Class( From 71bf00d2d98423630abc0dfcbc140d64840049a8 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Tue, 22 Jun 2021 23:38:22 -0700 Subject: [PATCH 2/3] bad merge --- lib/src/emitter.dart | 13 ++++++------- lib/src/specs/enum.g.dart | 4 ---- 2 files changed, 6 insertions(+), 11 deletions(-) diff --git a/lib/src/emitter.dart b/lib/src/emitter.dart index d0d02c1..d891f66 100644 --- a/lib/src/emitter.dart +++ b/lib/src/emitter.dart @@ -513,7 +513,6 @@ class DartEmitter extends Object bool optional = false, bool named = false, }) { - output ??= StringBuffer(); _visitDocs(spec.docs, output); spec.annotations.forEach((a) => visitAnnotation(a, output)); // The `required` keyword must precede the `covariant` keyword. @@ -592,15 +591,15 @@ class DartEmitter extends Object return out; } - StringSink _visitDocs(Iterable docs, [StringSink output]) { - output ??= StringBuffer(); + StringSink _visitDocs(Iterable docs, [StringSink? output]) { + final out = output ??= StringBuffer(); for (var doc in docs) { if (doc is Reference) { - output.write('['); - visitReference(doc, output); - output.writeln(']'); + out.write('['); + visitReference(doc, out); + out.writeln(']'); } else if (doc is String) { - output.writeln(doc); + out.writeln(doc); } else { throw ArgumentError( "doc is expected to be a String or a Reference, but '$doc' is a " diff --git a/lib/src/specs/enum.g.dart b/lib/src/specs/enum.g.dart index b4ac369..18a45dc 100644 --- a/lib/src/specs/enum.g.dart +++ b/lib/src/specs/enum.g.dart @@ -254,11 +254,7 @@ class _$EnumValueBuilder extends EnumValueBuilder { @override ListBuilder get docs { _$this; -<<<<<<< HEAD - return super.docs ??= new ListBuilder(); -======= return super.docs; ->>>>>>> master } @override From f26df9edaa0fd67d8fefbf7efefeddccdb44baf7 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Tue, 22 Jun 2021 23:42:10 -0700 Subject: [PATCH 3/3] comments --- lib/src/mixins/dartdoc.dart | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/lib/src/mixins/dartdoc.dart b/lib/src/mixins/dartdoc.dart index 264adf0..b2550ac 100644 --- a/lib/src/mixins/dartdoc.dart +++ b/lib/src/mixins/dartdoc.dart @@ -6,10 +6,16 @@ import 'package:built_collection/built_collection.dart'; abstract class HasDartDocs { /// Dart docs. + /// + /// This list may contain both [String]s and [Reference]s, so that elements + /// may be properly referenced with a prefix. BuiltList get docs; } abstract class HasDartDocsBuilder { /// Dart docs. + /// + /// This list may contain both [String]s and [Reference]s, so that elements + /// may be properly referenced with a prefix. abstract ListBuilder docs; }