Merge 760d291 into f9a875d

lib/src/model/documentation.dart

@@ -43,16 +43,17 @@ class Documentation {
 
   List<ModelCommentReference> 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;

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

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<md.Node> nodes, bool processFullDocs);
+  DocumentationRenderResult render(
+    List<md.Node> nodes, {
+    @required bool processFullDocs,
+  });
 }
 
-class DocumentationRendererHtml extends DocumentationRenderer {
+class DocumentationRendererHtml implements DocumentationRenderer {
+  const DocumentationRendererHtml();
+
   @override
-  DocumentationRenderResult render(List<md.Node> nodes, bool processFullDocs) {
+  DocumentationRenderResult render(
+    List<md.Node> 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});
 }

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<T extends ElementType> {
+  const ElementTypeRenderer();
+
   String renderLinkedName(T elementType);
 
   String renderNameWithGenerics(T elementType) => '';
@@ -22,6 +24,8 @@ abstract class ElementTypeRenderer<T extends ElementType> {
 
 class FunctionTypeElementTypeRendererHtml
     extends ElementTypeRenderer<FunctionTypeElementType> {
+  const FunctionTypeElementTypeRendererHtml();
+
   @override
   String renderLinkedName(FunctionTypeElementType elementType) {
     var buf = StringBuffer();
@@ -52,6 +56,8 @@ class FunctionTypeElementTypeRendererHtml
 
 class ParameterizedElementTypeRendererHtml
     extends ElementTypeRenderer<ParameterizedElementType> {
+  const ParameterizedElementTypeRendererHtml();
+
   @override
   String renderLinkedName(ParameterizedElementType elementType) {
     var buf = StringBuffer();
@@ -85,6 +91,8 @@ class ParameterizedElementTypeRendererHtml
 
 class AliasedElementTypeRendererHtml
     extends ElementTypeRenderer<AliasedElementType> {
+  const AliasedElementTypeRendererHtml();
+
   @override
   String renderLinkedName(AliasedElementType elementType) {
     var buf = StringBuffer();
@@ -118,6 +126,8 @@ class AliasedElementTypeRendererHtml
 
 class CallableElementTypeRendererHtml
     extends ElementTypeRenderer<CallableElementType> {
+  const CallableElementTypeRendererHtml();
+
   @override
   String renderLinkedName(CallableElementType elementType) {
     var buf = StringBuffer();
@@ -137,6 +147,8 @@ class CallableElementTypeRendererHtml
 
 class FunctionTypeElementTypeRendererMd
     extends ElementTypeRenderer<FunctionTypeElementType> {
+  const FunctionTypeElementTypeRendererMd();
+
   @override
   String renderLinkedName(FunctionTypeElementType elementType) {
     var buf = StringBuffer();
@@ -165,6 +177,8 @@ class FunctionTypeElementTypeRendererMd
 
 class ParameterizedElementTypeRendererMd
     extends ElementTypeRenderer<ParameterizedElementType> {
+  const ParameterizedElementTypeRendererMd();
+
   @override
   String renderLinkedName(ParameterizedElementType elementType) {
     var buf = StringBuffer();
@@ -196,6 +210,8 @@ class ParameterizedElementTypeRendererMd
 
 class AliasedElementTypeRendererMd
     extends ElementTypeRenderer<AliasedElementType> {
+  const AliasedElementTypeRendererMd();
+
   @override
   String renderLinkedName(AliasedElementType elementType) {
     var buf = StringBuffer();
@@ -227,6 +243,8 @@ class AliasedElementTypeRendererMd
 
 class CallableElementTypeRendererMd
     extends ElementTypeRenderer<CallableElementType> {
+  const CallableElementTypeRendererMd();
+
   @override
   String renderLinkedName(CallableElementType elementType) {
     var buf = StringBuffer();

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') {

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) {

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 <ol> tag.
 class ParameterRendererHtmlList extends ParameterRendererHtml {
+  const ParameterRendererHtmlList();
+
   @override
   String listItem(String listItem) => '<li>$listItem</li>\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,40 +105,40 @@ 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: ']',
           showMetadata: showMetadata,
           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<Parameter> parameters,
+  void _renderLinkedParameterSublist(
+      List<Parameter> 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();
   }
 }