diff --git a/lib/src/model/documentation.dart b/lib/src/model/documentation.dart index 6fe4697250..83461ace4b 100644 --- a/lib/src/model/documentation.dart +++ b/lib/src/model/documentation.dart @@ -43,16 +43,17 @@ class Documentation { List get commentRefs => _element.commentRefs; - void _renderDocumentation(bool processAllDocs) { - var parseResult = _parseDocumentation(processAllDocs); + void _renderDocumentation(bool processFullDocs) { + var parseResult = _parseDocumentation(processFullDocs); if (_hasExtendedDocs != null) { assert(_hasExtendedDocs == parseResult.hasExtendedDocs); } _hasExtendedDocs = parseResult.hasExtendedDocs; - var renderResult = _renderer.render(parseResult.nodes, processAllDocs); + var renderResult = + _renderer.render(parseResult.nodes, processFullDocs: processFullDocs); - if (processAllDocs) { + if (processFullDocs) { _asHtml = renderResult.asHtml; } _asOneLiner ??= renderResult.asOneLiner; diff --git a/lib/src/render/category_renderer.dart b/lib/src/render/category_renderer.dart index 66b7467bb0..0b6e838bc4 100644 --- a/lib/src/render/category_renderer.dart +++ b/lib/src/render/category_renderer.dart @@ -6,8 +6,6 @@ import 'package:dartdoc/src/model/category.dart'; /// A renderer for a [Category]. abstract class CategoryRenderer { - const CategoryRenderer(); - /// Render the label of this [category]. String renderCategoryLabel(Category category); @@ -17,7 +15,7 @@ abstract class CategoryRenderer { } /// A HTML renderer for a [Category]. -class CategoryRendererHtml extends CategoryRenderer { +class CategoryRendererHtml implements CategoryRenderer { const CategoryRendererHtml(); @override @@ -57,7 +55,7 @@ class CategoryRendererHtml extends CategoryRenderer { } /// A markdown renderer for a [Category]. -class CategoryRendererMd extends CategoryRenderer { +class CategoryRendererMd implements CategoryRenderer { const CategoryRendererMd(); @override diff --git a/lib/src/render/documentation_renderer.dart b/lib/src/render/documentation_renderer.dart index 5b2f28c36d..47b2351238 100644 --- a/lib/src/render/documentation_renderer.dart +++ b/lib/src/render/documentation_renderer.dart @@ -4,14 +4,23 @@ import 'package:html/parser.dart' show parse; import 'package:markdown/markdown.dart' as md; +import 'package:meta/meta.dart'; abstract class DocumentationRenderer { - DocumentationRenderResult render(List nodes, bool processFullDocs); + DocumentationRenderResult render( + List nodes, { + @required bool processFullDocs, + }); } -class DocumentationRendererHtml extends DocumentationRenderer { +class DocumentationRendererHtml implements DocumentationRenderer { + const DocumentationRendererHtml(); + @override - DocumentationRenderResult render(List nodes, bool processFullDocs) { + DocumentationRenderResult render( + List nodes, { + @required bool processFullDocs, + }) { if (nodes.isEmpty) { return DocumentationRenderResult.empty; } @@ -21,9 +30,7 @@ class DocumentationRendererHtml extends DocumentationRenderer { s.remove(); } for (var pre in asHtmlDocument.querySelectorAll('pre')) { - if (pre.children.isNotEmpty && - pre.children.length != 1 && - pre.children.first.localName != 'code') { + if (pre.children.length > 1 && pre.children.first.localName != 'code') { continue; } @@ -37,14 +44,14 @@ class DocumentationRendererHtml extends DocumentationRenderer { // Assume the user intended Dart if there are no other classes present. if (!specifiesLanguage) pre.classes.add('language-dart'); } - String asHtml; - String asOneLiner; + var asHtml = ''; if (processFullDocs) { - // `trim` fixes issue with line ending differences between mac and windows. + // `trim` fixes an issue with line ending differences between Mac and + // Windows. asHtml = asHtmlDocument.body.innerHtml?.trim(); } - asOneLiner = asHtmlDocument.body.children.isEmpty + var asOneLiner = asHtmlDocument.body.children.isEmpty ? '' : asHtmlDocument.body.children.first.innerHtml; @@ -58,5 +65,6 @@ class DocumentationRenderResult { final String /*?*/ asHtml; final String asOneLiner; - const DocumentationRenderResult({this.asHtml, this.asOneLiner = ''}); + const DocumentationRenderResult( + {@required this.asHtml, @required this.asOneLiner}); } diff --git a/lib/src/render/element_type_renderer.dart b/lib/src/render/element_type_renderer.dart index 5ac4dc090e..714e1c6daf 100644 --- a/lib/src/render/element_type_renderer.dart +++ b/lib/src/render/element_type_renderer.dart @@ -6,6 +6,8 @@ import 'package:dartdoc/dartdoc.dart'; import 'package:dartdoc/src/render/parameter_renderer.dart'; abstract class ElementTypeRenderer { + const ElementTypeRenderer(); + String renderLinkedName(T elementType); String renderNameWithGenerics(T elementType) => ''; @@ -22,6 +24,8 @@ abstract class ElementTypeRenderer { class FunctionTypeElementTypeRendererHtml extends ElementTypeRenderer { + const FunctionTypeElementTypeRendererHtml(); + @override String renderLinkedName(FunctionTypeElementType elementType) { var buf = StringBuffer(); @@ -52,6 +56,8 @@ class FunctionTypeElementTypeRendererHtml class ParameterizedElementTypeRendererHtml extends ElementTypeRenderer { + const ParameterizedElementTypeRendererHtml(); + @override String renderLinkedName(ParameterizedElementType elementType) { var buf = StringBuffer(); @@ -85,6 +91,8 @@ class ParameterizedElementTypeRendererHtml class AliasedElementTypeRendererHtml extends ElementTypeRenderer { + const AliasedElementTypeRendererHtml(); + @override String renderLinkedName(AliasedElementType elementType) { var buf = StringBuffer(); @@ -118,6 +126,8 @@ class AliasedElementTypeRendererHtml class CallableElementTypeRendererHtml extends ElementTypeRenderer { + const CallableElementTypeRendererHtml(); + @override String renderLinkedName(CallableElementType elementType) { var buf = StringBuffer(); @@ -137,6 +147,8 @@ class CallableElementTypeRendererHtml class FunctionTypeElementTypeRendererMd extends ElementTypeRenderer { + const FunctionTypeElementTypeRendererMd(); + @override String renderLinkedName(FunctionTypeElementType elementType) { var buf = StringBuffer(); @@ -165,6 +177,8 @@ class FunctionTypeElementTypeRendererMd class ParameterizedElementTypeRendererMd extends ElementTypeRenderer { + const ParameterizedElementTypeRendererMd(); + @override String renderLinkedName(ParameterizedElementType elementType) { var buf = StringBuffer(); @@ -196,6 +210,8 @@ class ParameterizedElementTypeRendererMd class AliasedElementTypeRendererMd extends ElementTypeRenderer { + const AliasedElementTypeRendererMd(); + @override String renderLinkedName(AliasedElementType elementType) { var buf = StringBuffer(); @@ -227,6 +243,8 @@ class AliasedElementTypeRendererMd class CallableElementTypeRendererMd extends ElementTypeRenderer { + const CallableElementTypeRendererMd(); + @override String renderLinkedName(CallableElementType elementType) { var buf = StringBuffer(); diff --git a/lib/src/render/enum_field_renderer.dart b/lib/src/render/enum_field_renderer.dart index c3ccf13e83..99f370fbd5 100644 --- a/lib/src/render/enum_field_renderer.dart +++ b/lib/src/render/enum_field_renderer.dart @@ -8,7 +8,9 @@ abstract class EnumFieldRenderer { String renderValue(EnumField field); } -class EnumFieldRendererHtml extends EnumFieldRenderer { +class EnumFieldRendererHtml implements EnumFieldRenderer { + const EnumFieldRendererHtml(); + @override String renderValue(EnumField field) { if (field.name == 'values') { @@ -19,7 +21,9 @@ class EnumFieldRendererHtml extends EnumFieldRenderer { } } -class EnumFieldRendererMd extends EnumFieldRenderer { +class EnumFieldRendererMd implements EnumFieldRenderer { + const EnumFieldRendererMd(); + @override String renderValue(EnumField field) { if (field.name == 'values') { diff --git a/lib/src/render/model_element_renderer.dart b/lib/src/render/model_element_renderer.dart index bb2e611656..63885667ef 100644 --- a/lib/src/render/model_element_renderer.dart +++ b/lib/src/render/model_element_renderer.dart @@ -6,6 +6,8 @@ import 'package:dartdoc/src/model/feature.dart'; import 'package:dartdoc/src/model/model_element.dart'; abstract class ModelElementRenderer { + const ModelElementRenderer(); + String renderLinkedName(ModelElement modelElement); String renderExtendedDocLink(ModelElement modelElement); @@ -22,6 +24,8 @@ abstract class ModelElementRenderer { } class ModelElementRendererHtml extends ModelElementRenderer { + const ModelElementRendererHtml(); + @override String renderLinkedName(ModelElement modelElement) { var cssClass = modelElement.isDeprecated ? ' class="deprecated"' : ''; @@ -103,6 +107,8 @@ class ModelElementRendererHtml extends ModelElementRenderer { } class ModelElementRendererMd extends ModelElementRendererHtml { + const ModelElementRendererMd(); + @override String renderLinkedName(ModelElement modelElement) { if (modelElement.isDeprecated) { diff --git a/lib/src/render/parameter_renderer.dart b/lib/src/render/parameter_renderer.dart index f263d5d36a..30376598d9 100644 --- a/lib/src/render/parameter_renderer.dart +++ b/lib/src/render/parameter_renderer.dart @@ -11,6 +11,8 @@ import 'package:meta/meta.dart' as meta; /// Render HTML in an extended vertical format using
    tag. class ParameterRendererHtmlList extends ParameterRendererHtml { + const ParameterRendererHtmlList(); + @override String listItem(String listItem) => '
  1. $listItem
    2. \n'; @override @@ -21,6 +23,8 @@ class ParameterRendererHtmlList extends ParameterRendererHtml { /// Render HTML suitable for a single, wrapped line. class ParameterRendererHtml extends ParameterRenderer { + const ParameterRendererHtml(); + @override String listItem(String listItem) => listItem; @override @@ -50,6 +54,8 @@ class ParameterRendererHtml extends ParameterRenderer { } class ParameterRendererMd extends ParameterRenderer { + const ParameterRendererMd(); + @override String annotation(String annotation) => annotation; @@ -79,6 +85,8 @@ class ParameterRendererMd extends ParameterRenderer { } abstract class ParameterRenderer { + const ParameterRenderer(); + String listItem(String item); String orderedList(String listItems); String annotation(String annotation); @@ -97,16 +105,16 @@ abstract class ParameterRenderer { parameters.where((Parameter p) => p.isOptionalPositional).toList(); var namedParams = parameters.where((Parameter p) => p.isNamed).toList(); - var positional = '', optional = '', named = ''; + var output = StringBuffer(); if (positionalParams.isNotEmpty) { - positional = _linkedParameterSublist(positionalParams, + _renderLinkedParameterSublist(positionalParams, output, trailingComma: optionalPositionalParams.isNotEmpty || namedParams.isNotEmpty, showMetadata: showMetadata, showNames: showNames); } if (optionalPositionalParams.isNotEmpty) { - optional = _linkedParameterSublist(optionalPositionalParams, + _renderLinkedParameterSublist(optionalPositionalParams, output, trailingComma: namedParams.isNotEmpty, openBracket: '[', closeBracket: ']', @@ -114,23 +122,23 @@ abstract class ParameterRenderer { showNames: showNames); } if (namedParams.isNotEmpty) { - named = _linkedParameterSublist(namedParams, + _renderLinkedParameterSublist(namedParams, output, trailingComma: false, openBracket: '{', closeBracket: '}', showMetadata: showMetadata, showNames: showNames); } - return orderedList(positional + optional + named); + return orderedList(output.toString()); } - String _linkedParameterSublist(List parameters, + void _renderLinkedParameterSublist( + List parameters, StringBuffer output, {@meta.required bool trailingComma, String openBracket = '', String closeBracket = '', - showMetadata = true, - showNames = true}) { - var builder = StringBuffer(); + bool showMetadata = true, + bool showNames = true}) { for (var p in parameters) { var prefix = ''; var suffix = ''; @@ -143,24 +151,32 @@ abstract class ParameterRenderer { } else { suffix += ', '; } - var renderedParam = - _renderParam(p, showMetadata: showMetadata, showNames: showNames); - builder.write( + var renderedParam = _renderParam(p, + prefix: prefix, + suffix: suffix, + showMetadata: showMetadata, + showNames: showNames); + output.write( listItem(parameter(prefix + renderedParam + suffix, p.htmlId))); } - return builder.toString(); } - String _renderParam(Parameter param, - {showMetadata = true, showNames = true}) { + String _renderParam( + Parameter param, { + @meta.required String prefix, + @meta.required String suffix, + bool showMetadata = true, + bool showNames = true, + }) { var buf = StringBuffer(); + buf.write(prefix); var paramModelType = param.modelType; if (showMetadata && param.hasAnnotations) { - buf.write(param.annotations - .map((a) => annotation(a.linkedNameWithParameters)) - .join(' ') + - ' '); + for (var a in param.annotations) { + buf.write(annotation(a.linkedNameWithParameters)); + buf.write(' '); + } } if (param.isRequiredNamed) { buf.write(required('required') + ' '); @@ -217,6 +233,8 @@ abstract class ParameterRenderer { buf.write(' = '); buf.write(defaultValue(param.defaultValue)); } + + buf.write(suffix); return buf.toString(); } } diff --git a/lib/src/render/renderer_factory.dart b/lib/src/render/renderer_factory.dart index 276008e9fb..9ecbc1157b 100644 --- a/lib/src/render/renderer_factory.dart +++ b/lib/src/render/renderer_factory.dart @@ -33,7 +33,7 @@ abstract class RendererFactory { } } - TemplateRenderer get templateRenderer; + LayoutRenderer get templateRenderer; CategoryRenderer get categoryRenderer; @@ -72,49 +72,50 @@ class HtmlRenderFactory extends RendererFactory { const HtmlRenderFactory(); @override - TemplateRenderer get templateRenderer => HtmlTemplateRenderer(); + LayoutRenderer get templateRenderer => const HtmlLayoutRenderer(); @override CategoryRenderer get categoryRenderer => const CategoryRendererHtml(); @override DocumentationRenderer get documentationRenderer => - DocumentationRendererHtml(); + const DocumentationRendererHtml(); @override ElementTypeRenderer get callableElementTypeRenderer => - CallableElementTypeRendererHtml(); + const CallableElementTypeRendererHtml(); @override ElementTypeRenderer get functionTypeElementTypeRenderer => - FunctionTypeElementTypeRendererHtml(); + const FunctionTypeElementTypeRendererHtml(); @override ElementTypeRenderer get parameterizedElementTypeRenderer => - ParameterizedElementTypeRendererHtml(); + const ParameterizedElementTypeRendererHtml(); @override ElementTypeRenderer get aliasedElementTypeRenderer => - AliasedElementTypeRendererHtml(); + const AliasedElementTypeRendererHtml(); @override - EnumFieldRenderer get enumFieldRenderer => EnumFieldRendererHtml(); + EnumFieldRenderer get enumFieldRenderer => const EnumFieldRendererHtml(); @override - ModelElementRenderer get modelElementRenderer => ModelElementRendererHtml(); + ModelElementRenderer get modelElementRenderer => + const ModelElementRendererHtml(); @override - ParameterRenderer get parameterRenderer => ParameterRendererHtml(); + ParameterRenderer get parameterRenderer => const ParameterRendererHtml(); @override ParameterRenderer get parameterRendererDetailed => - ParameterRendererHtmlList(); + const ParameterRendererHtmlList(); @override TypeParametersRenderer get typeParametersRenderer => - TypeParametersRendererHtml(); + const TypeParametersRendererHtml(); @override TypedefRenderer get typedefRenderer => const TypedefRendererHtml(); @@ -124,17 +125,17 @@ class HtmlRenderFactory extends RendererFactory { const LanguageFeatureRendererHtml(); @override - SourceCodeRenderer get sourceCodeRenderer => SourceCodeRendererHtml(); + SourceCodeRenderer get sourceCodeRenderer => const SourceCodeRendererHtml(); @override - FeatureRenderer get featureRenderer => FeatureRendererHtml(); + FeatureRenderer get featureRenderer => const FeatureRendererHtml(); } class MdRenderFactory extends RendererFactory { const MdRenderFactory(); @override - TemplateRenderer get templateRenderer => MdTemplateRenderer(); + LayoutRenderer get templateRenderer => const MdLayoutRenderer(); @override CategoryRenderer get categoryRenderer => const CategoryRendererMd(); @@ -143,41 +144,42 @@ class MdRenderFactory extends RendererFactory { // TODO(jdkoren): explore using documentation directly in the output file. @override DocumentationRenderer get documentationRenderer => - DocumentationRendererHtml(); + const DocumentationRendererHtml(); @override ElementTypeRenderer get callableElementTypeRenderer => - CallableElementTypeRendererMd(); + const CallableElementTypeRendererMd(); @override ElementTypeRenderer get functionTypeElementTypeRenderer => - FunctionTypeElementTypeRendererMd(); + const FunctionTypeElementTypeRendererMd(); @override ElementTypeRenderer get parameterizedElementTypeRenderer => - ParameterizedElementTypeRendererMd(); + const ParameterizedElementTypeRendererMd(); @override ElementTypeRenderer get aliasedElementTypeRenderer => - AliasedElementTypeRendererMd(); + const AliasedElementTypeRendererMd(); @override - EnumFieldRenderer get enumFieldRenderer => EnumFieldRendererMd(); + EnumFieldRenderer get enumFieldRenderer => const EnumFieldRendererMd(); @override - ModelElementRenderer get modelElementRenderer => ModelElementRendererMd(); + ModelElementRenderer get modelElementRenderer => + const ModelElementRendererMd(); @override - ParameterRenderer get parameterRenderer => ParameterRendererMd(); + ParameterRenderer get parameterRenderer => const ParameterRendererMd(); @override ParameterRenderer get parameterRendererDetailed => parameterRenderer; @override TypeParametersRenderer get typeParametersRenderer => - TypeParametersRendererMd(); + const TypeParametersRendererMd(); @override TypedefRenderer get typedefRenderer => const TypedefRendererMd(); @@ -187,8 +189,8 @@ class MdRenderFactory extends RendererFactory { const LanguageFeatureRendererMd(); @override - SourceCodeRenderer get sourceCodeRenderer => SourceCodeRendererNoop(); + SourceCodeRenderer get sourceCodeRenderer => const SourceCodeRendererNoop(); @override - FeatureRenderer get featureRenderer => FeatureRendererMd(); + FeatureRenderer get featureRenderer => const FeatureRendererMd(); } diff --git a/lib/src/render/source_code_renderer.dart b/lib/src/render/source_code_renderer.dart index 82e4d56150..0a15830d78 100644 --- a/lib/src/render/source_code_renderer.dart +++ b/lib/src/render/source_code_renderer.dart @@ -9,13 +9,17 @@ abstract class SourceCodeRenderer { String renderSourceCode(String source); } -class SourceCodeRendererNoop extends SourceCodeRenderer { +class SourceCodeRendererNoop implements SourceCodeRenderer { + const SourceCodeRendererNoop(); + @override String renderSourceCode(String source) => source; } /// [SourceCodeRenderer] that escapes characters for HTML. -class SourceCodeRendererHtml extends SourceCodeRenderer { +class SourceCodeRendererHtml implements SourceCodeRenderer { + const SourceCodeRendererHtml(); + @override String renderSourceCode(String source) { return (const HtmlEscape()).convert(source); diff --git a/lib/src/render/template_renderer.dart b/lib/src/render/template_renderer.dart index 456d20c74a..24da3e01ca 100644 --- a/lib/src/render/template_renderer.dart +++ b/lib/src/render/template_renderer.dart @@ -2,11 +2,13 @@ // 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. -abstract class TemplateRenderer { +abstract class LayoutRenderer { String composeLayoutTitle(String name, String kind, bool isDeprecated); } -class HtmlTemplateRenderer implements TemplateRenderer { +class HtmlLayoutRenderer implements LayoutRenderer { + const HtmlLayoutRenderer(); + @override String composeLayoutTitle(String name, String kind, bool isDeprecated) { if (isDeprecated) { @@ -17,7 +19,9 @@ class HtmlTemplateRenderer implements TemplateRenderer { } } -class MdTemplateRenderer implements TemplateRenderer { +class MdLayoutRenderer implements LayoutRenderer { + const MdLayoutRenderer(); + @override String composeLayoutTitle(String name, String kind, bool isDeprecated) { if (isDeprecated) { diff --git a/lib/src/render/type_parameters_renderer.dart b/lib/src/render/type_parameters_renderer.dart index 544803d53d..d688962eba 100644 --- a/lib/src/render/type_parameters_renderer.dart +++ b/lib/src/render/type_parameters_renderer.dart @@ -10,7 +10,9 @@ abstract class TypeParametersRenderer { String renderLinkedGenericParameters(TypeParameters typeParameters); } -class TypeParametersRendererHtml extends TypeParametersRenderer { +class TypeParametersRendererHtml implements TypeParametersRenderer { + const TypeParametersRendererHtml(); + @override String renderGenericParameters(TypeParameters typeParameters) { if (typeParameters.typeParameters.isEmpty) { @@ -34,7 +36,9 @@ class TypeParametersRendererHtml extends TypeParametersRenderer { } } -class TypeParametersRendererMd extends TypeParametersRenderer { +class TypeParametersRendererMd implements TypeParametersRenderer { + const TypeParametersRendererMd(); + @override String renderGenericParameters(TypeParameters typeParameters) => _compose(typeParameters.typeParameters, (t) => t.name); diff --git a/test/render/template_renderer_test.dart b/test/render/template_renderer_test.dart index 1340143d46..379da3e0aa 100644 --- a/test/render/template_renderer_test.dart +++ b/test/render/template_renderer_test.dart @@ -7,10 +7,10 @@ import 'package:test/test.dart'; void main() { group('HtmlTemplateRenderer', () { - HtmlTemplateRenderer renderer; + HtmlLayoutRenderer renderer; setUpAll(() { - renderer = HtmlTemplateRenderer(); + renderer = HtmlLayoutRenderer(); }); test('composeLayoutTitle', () { @@ -25,10 +25,10 @@ void main() { }); group('MdTemplateRenderer', () { - MdTemplateRenderer renderer; + MdLayoutRenderer renderer; setUpAll(() { - renderer = MdTemplateRenderer(); + renderer = MdLayoutRenderer(); }); test('composeLayoutTitle', () {