Skip to content
This repository was archived by the owner on Apr 8, 2025. It is now read-only.

Support References in docs #311

Closed
wants to merge 4 commits into from
Closed

Support References in docs #311

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
9c2e261
Support References in docs
srawlins Mar 8, 2021
176da1d
Merge branch 'master' into docs-with-refer
srawlins Jun 23, 2021
71bf00d
bad merge
srawlins Jun 23, 2021
f26df9e
comments
srawlins Jun 23, 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
32 changes: 25 additions & 7 deletions lib/src/emitter.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ class DartEmitter extends Object
@override
StringSink visitClass(Class spec, [StringSink? output]) {
final out = output ??= StringBuffer();
spec.docs.forEach(out.writeln);
_visitDocs(spec.docs, out);
spec.annotations.forEach((a) => visitAnnotation(a, out));
if (spec.abstract) {
out.write('abstract ');
Expand Down Expand Up @@ -154,7 +154,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 ');
Expand Down Expand Up @@ -238,7 +238,7 @@ class DartEmitter extends Object
@override
StringSink visitExtension(Extension spec, [StringSink? output]) {
final out = output ??= StringBuffer();
spec.docs.forEach(out.writeln);
_visitDocs(spec.docs, out);
spec.annotations.forEach((a) => visitAnnotation(a, out));

out.write('extension');
Expand Down Expand Up @@ -306,7 +306,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 ');
Expand Down Expand Up @@ -420,7 +420,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 ');
Expand Down Expand Up @@ -513,7 +513,7 @@ class DartEmitter extends Object
bool optional = false,
bool named = false,
}) {
spec.docs.forEach(output.writeln);
_visitDocs(spec.docs, output);
spec.annotations.forEach((a) => visitAnnotation(a, output));
// The `required` keyword must precede the `covariant` keyword.
if (spec.required) {
Expand Down Expand Up @@ -576,7 +576,7 @@ class DartEmitter extends Object
@override
StringSink visitEnum(Enum spec, [StringSink? output]) {
final out = output ??= StringBuffer();
spec.docs.forEach(out.writeln);
_visitDocs(spec.docs, out);
spec.annotations.forEach((a) => visitAnnotation(a, out));
out.writeln('enum ${spec.name} {');
spec.values.forEach((v) {
Expand All @@ -590,6 +590,24 @@ class DartEmitter extends Object
out.writeln('}');
return out;
}

StringSink _visitDocs(Iterable<Object> docs, [StringSink? output]) {
final out = output ??= StringBuffer();
for (var doc in docs) {
if (doc is Reference) {
out.write('[');
visitReference(doc, out);
out.writeln(']');
} else if (doc is String) {
out.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:
Expand Down
10 changes: 8 additions & 2 deletions lib/src/mixins/dartdoc.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,16 @@ import 'package:built_collection/built_collection.dart';

abstract class HasDartDocs {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's add comments here and below why Object is being used and what a valid type is (and isn't).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

/// Dart docs.
BuiltList<String> get docs;
///
/// This list may contain both [String]s and [Reference]s, so that elements
/// may be properly referenced with a prefix.
BuiltList<Object> get docs;
}

abstract class HasDartDocsBuilder {
/// Dart docs.
abstract ListBuilder<String> docs;
///
/// This list may contain both [String]s and [Reference]s, so that elements
/// may be properly referenced with a prefix.
abstract ListBuilder<Object> docs;
}
4 changes: 2 additions & 2 deletions lib/src/specs/class.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ abstract class Class extends Object
BuiltList<Expression> get annotations;

@override
BuiltList<String> get docs;
BuiltList<Object> get docs;

Reference? get extend;

Expand Down Expand Up @@ -79,7 +79,7 @@ abstract class ClassBuilder extends Object
ListBuilder<Expression> annotations = ListBuilder<Expression>();

@override
ListBuilder<String> docs = ListBuilder<String>();
ListBuilder<Object> docs = ListBuilder<Object>();

Reference? extend;

Expand Down
6 changes: 3 additions & 3 deletions lib/src/specs/class.g.dart
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions lib/src/specs/constructor.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ abstract class Constructor extends Object
BuiltList<Expression> get annotations;

@override
BuiltList<String> get docs;
BuiltList<Object> get docs;

/// Optional parameters.
BuiltList<Parameter> get optionalParameters;
Expand Down Expand Up @@ -72,7 +72,7 @@ abstract class ConstructorBuilder extends Object
ListBuilder<Expression> annotations = ListBuilder<Expression>();

@override
ListBuilder<String> docs = ListBuilder<String>();
ListBuilder<Object> docs = ListBuilder<Object>();

/// Optional parameters.
ListBuilder<Parameter> optionalParameters = ListBuilder<Parameter>();
Expand Down
6 changes: 3 additions & 3 deletions lib/src/specs/constructor.g.dart
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions lib/src/specs/enum.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ abstract class Enum extends Object
BuiltList<Expression> get annotations;

@override
BuiltList<String> get docs;
BuiltList<Object> get docs;

@override
R accept<R>(
Expand All @@ -54,7 +54,7 @@ abstract class EnumBuilder extends Object
ListBuilder<Expression> annotations = ListBuilder<Expression>();

@override
ListBuilder<String> docs = ListBuilder<String>();
ListBuilder<Object> docs = ListBuilder<Object>();
}

@immutable
Expand All @@ -71,7 +71,7 @@ abstract class EnumValue extends Object
BuiltList<Expression> get annotations;

@override
BuiltList<String> get docs;
BuiltList<Object> get docs;
}

abstract class EnumValueBuilder extends Object
Expand All @@ -87,5 +87,5 @@ abstract class EnumValueBuilder extends Object
ListBuilder<Expression> annotations = ListBuilder<Expression>();

@override
ListBuilder<String> docs = ListBuilder<String>();
ListBuilder<Object> docs = ListBuilder<Object>();
}
12 changes: 6 additions & 6 deletions lib/src/specs/enum.g.dart
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions lib/src/specs/extension.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ abstract class Extension extends Object
BuiltList<Expression> get annotations;

@override
BuiltList<String> get docs;
BuiltList<Object> get docs;

Reference? get on;

Expand Down Expand Up @@ -63,7 +63,7 @@ abstract class ExtensionBuilder extends Object
ListBuilder<Expression> annotations = ListBuilder<Expression>();

@override
ListBuilder<String> docs = ListBuilder<String>();
ListBuilder<Object> docs = ListBuilder<Object>();

Reference? on;

Expand Down
6 changes: 3 additions & 3 deletions lib/src/specs/extension.g.dart
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions lib/src/specs/field.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ abstract class Field extends Object
BuiltList<Expression> get annotations;

@override
BuiltList<String> get docs;
BuiltList<Object> get docs;

/// Field assignment, if any.
Code? get assignment;
Expand Down Expand Up @@ -70,7 +70,7 @@ abstract class FieldBuilder extends Object
ListBuilder<Expression> annotations = ListBuilder<Expression>();

@override
ListBuilder<String> docs = ListBuilder<String>();
ListBuilder<Object> docs = ListBuilder<Object>();

/// Field assignment, if any.
Code? assignment;
Expand Down
6 changes: 3 additions & 3 deletions lib/src/specs/field.g.dart
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions lib/src/specs/method.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ abstract class Method extends Object
BuiltList<Expression> get annotations;

@override
BuiltList<String> get docs;
BuiltList<Object> get docs;

@override
BuiltList<Reference> get types;
Expand Down Expand Up @@ -109,7 +109,7 @@ abstract class MethodBuilder extends Object
ListBuilder<Expression> annotations = ListBuilder<Expression>();

@override
ListBuilder<String> docs = ListBuilder<String>();
ListBuilder<Object> docs = ListBuilder<Object>();

@override
ListBuilder<Reference> types = ListBuilder<Reference>();
Expand Down Expand Up @@ -184,7 +184,7 @@ abstract class Parameter extends Object
BuiltList<Expression> get annotations;

@override
BuiltList<String> get docs;
BuiltList<Object> get docs;

@override
BuiltList<Reference> get types;
Expand Down Expand Up @@ -236,7 +236,7 @@ abstract class ParameterBuilder extends Object
ListBuilder<Expression> annotations = ListBuilder<Expression>();

@override
ListBuilder<String> docs = ListBuilder<String>();
ListBuilder<Object> docs = ListBuilder<Object>();

@override
ListBuilder<Reference> types = ListBuilder<Reference>();
Expand Down
Loading