Google Git
Sign in
dart / dartdoc / 578400cb94074291f341255530e6415e9cf10f05^! / .
commit578400cb94074291f341255530e6415e9cf10f05[log] [tgz]
authorJonathan Koren <jdkoren@google.com>Mon Mar 30 12:33:12 2020 -0700
committerGitHub <noreply@github.com>Mon Mar 30 12:33:12 2020 -0700
tree590d588172161cde9b03ea2c1e8a62c9f5dec2bd
parent98fb869269a28ff8eef23fe11a813bd8ef56ce55 [diff]
Markdown template tweaks (#2162)

* Add some spacing

* Colon syntax for definition doesn't work, so remove it

* tweak features display

* Category tweaks

* Use h5

* Slightly more verbose source link

* Escape opening angle bracket on type parameters
diff --git a/lib/src/model/categorization.dart b/lib/src/model/categorization.dart
index 11eee24..634403e 100644
--- a/lib/src/model/categorization.dart
+++ b/lib/src/model/categorization.dart

@@ -114,6 +114,8 @@
     return categories.where((c) => c.isDocumented);
   }
 
+  bool get hasDisplayedCategories => displayedCategories.isNotEmpty;
+
   /// True if categories, subcategories, a documentation icon, or samples were
   /// declared.
   bool get hasCategorization {

diff --git a/lib/src/render/type_parameters_renderer.dart b/lib/src/render/type_parameters_renderer.dart
index 09ac2ee..b99f0e6 100644
--- a/lib/src/render/type_parameters_renderer.dart
+++ b/lib/src/render/type_parameters_renderer.dart

@@ -49,6 +49,6 @@
       return '';
     }
     var joined = typeParameters.map(mapfn).join(', ');
-    return '<${joined}>';
+    return '&lt;${joined}>';
   }
 }

diff --git a/lib/templates/md/_accessor_getter.md b/lib/templates/md/_accessor_getter.md
index ec5ff77..b04c749 100644
--- a/lib/templates/md/_accessor_getter.md
+++ b/lib/templates/md/_accessor_getter.md

@@ -1,7 +1,8 @@
 {{#getter}}
-{{{ linkedReturnType }}} {{>name_summary}}
+{{{ linkedReturnType }}} {{>name_summary}}  {{!two spaces intentional}}
 {{>features}}
 
 {{>documentation}}
+
 {{>source_code}}
 {{/getter}}

diff --git a/lib/templates/md/_accessor_setter.md b/lib/templates/md/_accessor_setter.md
index 896bcbc..852a302 100644
--- a/lib/templates/md/_accessor_setter.md
+++ b/lib/templates/md/_accessor_setter.md

@@ -1,7 +1,8 @@
 {{#setter}}
-{{>name_summary}}({{{ linkedParamsNoMetadata }}})
+{{>name_summary}}({{{ linkedParamsNoMetadata }}})  {{!two spaces intentional}}
 {{>features}}
 
 {{>documentation}}
+
 {{>source_code}}
 {{/setter}}

diff --git a/lib/templates/md/_callable.md b/lib/templates/md/_callable.md
index 9cc8684..12560c7 100644
--- a/lib/templates/md/_callable.md
+++ b/lib/templates/md/_callable.md

@@ -1,3 +1,5 @@
-{{{linkedName}}}{{{linkedGenericParameters}}}({{{ linkedParamsNoMetadata }}}) {{{ linkedReturnType }}} {{>categorization}}
-: {{{ oneLineDoc }}} {{{ extendedDocLink }}}
+##### {{{linkedName}}}{{{linkedGenericParameters}}}({{{ linkedParamsNoMetadata }}}) {{{ linkedReturnType }}}
+{{>categorization}}
+
+{{{ oneLineDoc }}} {{{ extendedDocLink }}}  {{!two spaces intentional}}
 {{>features}}

diff --git a/lib/templates/md/_categorization.md b/lib/templates/md/_categorization.md
index 53ace95..3be4858 100644
--- a/lib/templates/md/_categorization.md
+++ b/lib/templates/md/_categorization.md

@@ -1,5 +1,6 @@
-{{#hasCategoryNames}}
+{{#hasDisplayedCategories}}
+Categories:
 {{#displayedCategories}}
 {{{categoryLabel}}}
 {{/displayedCategories}}
-{{/hasCategoryNames}}
+{{/hasDisplayedCategories}}

diff --git a/lib/templates/md/_class.md b/lib/templates/md/_class.md
index 7659fa0..e5dac11 100644
--- a/lib/templates/md/_class.md
+++ b/lib/templates/md/_class.md

@@ -1,2 +1,4 @@
-{{{linkedName}}}{{{linkedGenericParameters}}} {{>categorization}}
-: {{{ oneLineDoc }}} {{{ extendedDocLink }}}
+##### {{{linkedName}}}{{{linkedGenericParameters}}}
+{{>categorization}}
+
+{{{ oneLineDoc }}} {{{ extendedDocLink }}}

diff --git a/lib/templates/md/_constant.md b/lib/templates/md/_constant.md
index 6367e59..c7e3745 100644
--- a/lib/templates/md/_constant.md
+++ b/lib/templates/md/_constant.md

@@ -1,3 +1,5 @@
-{{{ linkedName }}} const {{{ linkedReturnType }}} {{>categorization}}
-: {{{ oneLineDoc }}} {{{ extendedDocLink }}}
+##### {{{ linkedName }}} const {{{ linkedReturnType }}}
+{{>categorization}}
+
+{{{ oneLineDoc }}} {{{ extendedDocLink }}}  {{!two spaces intentional}}
 {{>features}}

diff --git a/lib/templates/md/_extension.md b/lib/templates/md/_extension.md
index 84737c4..7c3bb25 100644
--- a/lib/templates/md/_extension.md
+++ b/lib/templates/md/_extension.md

@@ -1,2 +1,4 @@
-{{{linkedName}}} {{>categorization}}
-: {{{ oneLineDoc }}} {{{ extendedDocLink }}}
+##### {{{linkedName}}}
+{{>categorization}}
+
+{{{ oneLineDoc }}} {{{ extendedDocLink }}}

diff --git a/lib/templates/md/_library.md b/lib/templates/md/_library.md
index 1ee6866..33e7825 100644
--- a/lib/templates/md/_library.md
+++ b/lib/templates/md/_library.md

@@ -1,4 +1,5 @@
-{{{ linkedName }}} ({{>categorization}})
+##### {{{ linkedName }}}
 {{#isDocumented}}
-: {{{ oneLineDoc }}} {{{ extendedDocLink }}}
+{{{ oneLineDoc }}} {{{ extendedDocLink }}}
+
 {{/isDocumented}}

diff --git a/lib/templates/md/_mixin.md b/lib/templates/md/_mixin.md
index 7659fa0..e5dac11 100644
--- a/lib/templates/md/_mixin.md
+++ b/lib/templates/md/_mixin.md

@@ -1,2 +1,4 @@
-{{{linkedName}}}{{{linkedGenericParameters}}} {{>categorization}}
-: {{{ oneLineDoc }}} {{{ extendedDocLink }}}
+##### {{{linkedName}}}{{{linkedGenericParameters}}}
+{{>categorization}}
+
+{{{ oneLineDoc }}} {{{ extendedDocLink }}}

diff --git a/lib/templates/md/_property.md b/lib/templates/md/_property.md
index e02f8d5..64883ef 100644
--- a/lib/templates/md/_property.md
+++ b/lib/templates/md/_property.md

@@ -1,3 +1,5 @@
-{{{linkedName}}} {{{ arrow }}} {{{ linkedReturnType }}} {{>categorization}}
-: {{{ oneLineDoc }}} {{{ extendedDocLink }}}
+##### {{{linkedName}}} {{{ arrow }}} {{{ linkedReturnType }}}
+{{>categorization}}
+
+{{{ oneLineDoc }}} {{{ extendedDocLink }}}  {{!two spaces intentional}}
 {{>features}}

diff --git a/lib/templates/md/_source_link.md b/lib/templates/md/_source_link.md
index 3da6c52..88350d7 100644
--- a/lib/templates/md/_source_link.md
+++ b/lib/templates/md/_source_link.md

@@ -1,3 +1,3 @@
 {{#hasSourceHref}}
-[source]({{{sourceHref}}})
+[view source]({{{sourceHref}}})
 {{/hasSourceHref}}

diff --git a/lib/templates/md/category.md b/lib/templates/md/category.md
index ebdddcb..fb4f9a1 100644
--- a/lib/templates/md/category.md
+++ b/lib/templates/md/category.md

@@ -10,6 +10,7 @@
 
 {{#publicLibraries}}
 {{>library}}
+
 {{/publicLibraries}}
 {{/hasPublicLibraries}}
 
@@ -18,6 +19,7 @@
 
 {{#publicClasses}}
 {{>class}}
+
 {{/publicClasses}}
 {{/hasPublicClasses}}
 
@@ -26,6 +28,7 @@
 
 {{#publicMixins}}
 {{>mixin}}
+
 {{/publicMixins}}
 {{/hasPublicMixins}}
 
@@ -34,6 +37,7 @@
 
 {{#publicConstants}}
 {{>constant}}
+
 {{/publicConstants}}
 {{/hasPublicConstants}}
 
@@ -42,6 +46,7 @@
 
 {{#publicProperties}}
 {{>property}}
+
 {{/publicProperties}}
 {{/hasPublicProperties}}
 
@@ -50,6 +55,7 @@
 
 {{#publicFunctions}}
 {{>callable}}
+
 {{/publicFunctions}}
 {{/hasPublicFunctions}}
 
@@ -58,6 +64,7 @@
 
 {{#publicEnums}}
 {{>class}}
+
 {{/publicEnums}}
 {{/hasPublicEnums}}
 
@@ -66,6 +73,7 @@
 
 {{#publicTypedefs}}
 {{>callable}}
+
 {{/publicTypedefs}}
 {{/hasPublicTypedefs}}
 
@@ -74,6 +82,7 @@
 
 {{#publicExceptions}}
 {{>class}}
+
 {{/publicExceptions}}
 {{/hasPublicExceptions}}
 {{/self}}

diff --git a/lib/templates/md/class.md b/lib/templates/md/class.md
index 531f97f..d9cb249 100644
--- a/lib/templates/md/class.md
+++ b/lib/templates/md/class.md

@@ -67,8 +67,10 @@
 
 {{#publicConstructors}}
 {{{linkedName}}} ({{{ linkedParams }}})
-: {{{ oneLineDoc }}} {{{ extendedDocLink }}}
-{{#isConst}}const{{/isConst}} {{#isFactory}}factory{{/isFactory}}
+
+{{{ oneLineDoc }}} {{{ extendedDocLink }}}  {{!two spaces intentional}}
+{{#isConst}}_const_{{/isConst}} {{#isFactory}}_factory_{{/isFactory}}
+
 {{/publicConstructors}}
 {{/hasPublicConstructors}}
 
@@ -77,6 +79,7 @@
 
 {{#allPublicInstanceProperties}}
 {{>property}}
+
 {{/allPublicInstanceProperties}}
 {{/hasPublicProperties}}
 
@@ -85,6 +88,7 @@
 
 {{#allPublicInstanceMethods}}
 {{>callable}}
+
 {{/allPublicInstanceMethods}}
 {{/hasPublicMethods}}
 
@@ -93,6 +97,7 @@
 
 {{#allPublicOperators}}
 {{>callable}}
+
 {{/allPublicOperators}}
 {{/hasPublicOperators}}
 
@@ -101,6 +106,7 @@
 
 {{#publicStaticProperties}}
 {{>property}}
+
 {{/publicStaticProperties}}
 {{/hasPublicStaticProperties}}
 
@@ -109,6 +115,7 @@
 
 {{#publicStaticMethods}}
 {{>callable}}
+
 {{/publicStaticMethods}}
 {{/hasPublicStaticMethods}}
 
@@ -117,6 +124,7 @@
 
 {{#publicConstants}}
 {{>constant}}
+
 {{/publicConstants}}
 {{/hasPublicConstants}}
 {{/clazz}}

diff --git a/lib/templates/md/constant.md b/lib/templates/md/constant.md
index 689c4c7..3f5abcb 100644
--- a/lib/templates/md/constant.md
+++ b/lib/templates/md/constant.md

@@ -10,6 +10,7 @@
 {{{ linkedReturnType }}} {{>name_summary}} = {{{ constantValue }}}
 
 {{>documentation}}
+
 {{>source_code}}
 {{/property}}
 

diff --git a/lib/templates/md/enum.md b/lib/templates/md/enum.md
index 011cf40..727e6be 100644
--- a/lib/templates/md/enum.md
+++ b/lib/templates/md/enum.md

@@ -59,6 +59,7 @@
 
 {{#publicConstants}}
 {{>constant}}
+
 {{/publicConstants}}
 {{/hasPublicConstants}}
 
@@ -66,9 +67,11 @@
 ## Constructors
 
 {{#publicConstructors}}
-{{{linkedName}}} ({{{ linkedParams }}})
-: {{{ oneLineDoc }}} {{{ extendedDocLink }}}
-{{#isConst}}const{{/isConst}} {{#isFactory}}factory{{/isFactory}}
+{{{linkedName}}}({{{ linkedParams }}})
+
+{{{ oneLineDoc }}} {{{ extendedDocLink }}}  {{!two spaces intentional}}
+{{#isConst}}_const_{{/isConst}} {{#isFactory}}_factory_{{/isFactory}}
+
 {{/publicConstructors}}
 {{/hasPublicConstructors}}
 
@@ -77,6 +80,7 @@
 
 {{#allPublicInstanceProperties}}
 {{>property}}
+
 {{/allPublicInstanceProperties}}
 {{/hasPublicProperties}}
 
@@ -85,6 +89,7 @@
 
 {{#allPublicInstanceMethods}}
 {{>callable}}
+
 {{/allPublicInstanceMethods}}
 {{/hasPublicMethods}}
 
@@ -93,6 +98,7 @@
 
 {{#allPublicOperators}}
 {{>callable}}
+
 {{/allPublicOperators}}
 {{/hasPublicOperators}}
 
@@ -101,6 +107,7 @@
 
 {{#publicStaticProperties}}
 {{>property}}
+
 {{/publicStaticProperties}}
 {{/hasPublicStaticProperties}}
 
@@ -109,6 +116,7 @@
 
 {{#publicStaticMethods}}
 {{>callable}}
+
 {{/publicStaticMethods}}
 {{/hasPublicStaticMethods}}
 {{/eNum}}

diff --git a/lib/templates/md/extension.md b/lib/templates/md/extension.md
index ab247ab..aa7c992 100644
--- a/lib/templates/md/extension.md
+++ b/lib/templates/md/extension.md

@@ -2,24 +2,22 @@
 
 {{#self}}
 # {{{nameWithGenerics}}} {{kind}}
+on {{#extendedType}}{{{linkedName}}}{{/extendedType}}
 
 {{>source_link}}
+
 {{>categorization}}
 {{/self}}
 
 {{#extension}}
 {{>documentation}}
 
-on
-{{#extendedType}}
-: {{{linkedName}}}
-{{/extendedType}}
-
 {{#hasPublicProperties}}
 ## Properties
 
 {{#allPublicInstanceProperties}}
 {{>property}}
+
 {{/allPublicInstanceProperties}}
 {{/hasPublicProperties}}
 
@@ -28,6 +26,7 @@
 
 {{#allPublicInstanceMethods}}
 {{>callable}}
+
 {{/allPublicInstanceMethods}}
 {{/hasPublicMethods}}
 
@@ -36,6 +35,7 @@
 
 {{#allPublicOperators}}
 {{>callable}}
+
 {{/allPublicOperators}}
 {{/hasPublicOperators}}
 
@@ -44,6 +44,7 @@
 
 {{#publicStaticProperties}}
 {{>property}}
+
 {{/publicStaticProperties}}
 {{/hasPublicStaticProperties}}
 
@@ -52,6 +53,7 @@
 
 {{#publicStaticMethods}}
 {{>callable}}
+
 {{/publicStaticMethods}}
 {{/hasPublicStaticMethods}}
 
@@ -60,6 +62,7 @@
 
 {{#publicConstants}}
 {{>constant}}
+
 {{/publicConstants}}
 {{/hasPublicConstants}}
 {{/extension}}

diff --git a/lib/templates/md/index.md b/lib/templates/md/index.md
index 1823757..ca0e03e 100644
--- a/lib/templates/md/index.md
+++ b/lib/templates/md/index.md

@@ -20,7 +20,7 @@
 {{/defaultCategory.publicLibraries}}
 
 {{#categoriesWithPublicLibraries}}
-### {{name}}
+### Category {{{categoryLabel}}}
 
 {{#publicLibraries}}
 {{>library}}

diff --git a/lib/templates/md/library.md b/lib/templates/md/library.md
index a413873..f338b40 100644
--- a/lib/templates/md/library.md
+++ b/lib/templates/md/library.md

@@ -16,6 +16,7 @@
 
 {{#library.publicClasses}}
 {{>class}}
+
 {{/library.publicClasses}}
 {{/library.hasPublicClasses}}
 
@@ -24,6 +25,7 @@
 
 {{#library.publicMixins}}
 {{>mixin}}
+
 {{/library.publicMixins}}
 {{/library.hasPublicMixins}}
 
@@ -32,6 +34,7 @@
 
 {{#library.publicExtensions}}
 {{>extension}}
+
 {{/library.publicExtensions}}
 {{/library.hasPublicExtensions}}
 
@@ -40,6 +43,7 @@
 
 {{#library.publicConstants}}
 {{>constant}}
+
 {{/library.publicConstants}}
 {{/library.hasPublicConstants}}
 
@@ -48,6 +52,7 @@
 
 {{#library.publicProperties}}
 {{>property}}
+
 {{/library.publicProperties}}
 {{/library.hasPublicProperties}}
 
@@ -56,6 +61,7 @@
 
 {{#library.publicFunctions}}
 {{>callable}}
+
 {{/library.publicFunctions}}
 {{/library.hasPublicFunctions}}
 
@@ -64,6 +70,7 @@
 
 {{#library.publicEnums}}
 {{>class}}
+
 {{/library.publicEnums}}
 {{/library.hasPublicEnums}}
 
@@ -72,6 +79,7 @@
 
 {{#library.publicTypedefs}}
 {{>callable}}
+
 {{/library.publicTypedefs}}
 {{/library.hasPublicTypedefs}}
 
@@ -80,6 +88,7 @@
 
 {{#library.publicExceptions}}
 {{>class}}
+
 {{/library.publicExceptions}}
 {{/library.hasPublicExceptions}}
 

diff --git a/lib/templates/md/method.md b/lib/templates/md/method.md
index 8868aa3..0d03ab4 100644
--- a/lib/templates/md/method.md
+++ b/lib/templates/md/method.md

@@ -9,6 +9,7 @@
 {{#method}}
 {{>callable_multiline}}
 {{>features}}
+
 {{>documentation}}
 
 {{>source_code}}

diff --git a/lib/templates/md/mixin.md b/lib/templates/md/mixin.md
index 6bd7ebf..8060f5e 100644
--- a/lib/templates/md/mixin.md
+++ b/lib/templates/md/mixin.md

@@ -66,9 +66,11 @@
 ## Constructors
 
 {{#publicConstructors}}
-{{{linkedName}}} ({{{ linkedParams }}})
-: {{{ oneLineDoc }}} {{{ extendedDocLink }}}
-{{#isConst}}const{{/isConst}} {{#isFactory}}factory{{/isFactory}}
+{{{linkedName}}}({{{ linkedParams }}})
+
+{{{ oneLineDoc }}} {{{ extendedDocLink }}}  {{!two spaces intentional}}
+{{#isConst}}_const_{{/isConst}} {{#isFactory}}_factory_{{/isFactory}}
+
 {{/publicConstructors}}
 {{/hasPublicConstructors}}
 
@@ -77,6 +79,7 @@
 
 {{#allPublicInstanceProperties}}
 {{>property}}
+
 {{/allPublicInstanceProperties}}
 {{/hasPublicProperties}}
 
@@ -85,6 +88,7 @@
 
 {{#allPublicInstanceMethods}}
 {{>callable}}
+
 {{/allPublicInstanceMethods}}
 {{/hasPublicMethods}}
 
@@ -93,6 +97,7 @@
 
 {{#allPublicOperators}}
 {{>callable}}
+
 {{/allPublicOperators}}
 {{/hasPublicOperators}}
 
@@ -101,6 +106,7 @@
 
 {{#publicStaticProperties}}
 {{>property}}
+
 {{/publicStaticProperties}}
 {{/hasPublicStaticProperties}}
 
@@ -109,6 +115,7 @@
 
 {{#publicStaticMethods}}
 {{>callable}}
+
 {{/publicStaticMethods}}
 {{/hasPublicStaticMethods}}
 
@@ -117,6 +124,7 @@
 
 {{#publicConstants}}
 {{>constant}}
+
 {{/publicConstants}}
 {{/hasPublicConstants}}
 {{/mixin}}

diff --git a/lib/templates/md/property.md b/lib/templates/md/property.md
index c3f160b..351e51e 100644
--- a/lib/templates/md/property.md
+++ b/lib/templates/md/property.md

@@ -8,10 +8,11 @@
 
 {{#self}}
 {{#hasNoGetterSetter}}
-{{{ linkedReturnType }}} {{>name_summary}}
+{{{ linkedReturnType }}} {{>name_summary}}  {{!two spaces intentional}}
 {{>features}}
 
 {{>documentation}}
+
 {{>source_code}}
 {{/hasNoGetterSetter}}
 

diff --git a/lib/templates/md/top_level_constant.md b/lib/templates/md/top_level_constant.md
index edb5327..1f79709 100644
--- a/lib/templates/md/top_level_constant.md
+++ b/lib/templates/md/top_level_constant.md

@@ -6,10 +6,11 @@
 {{>source_link}}
 {{>categorization}}
 
-{{>name_summary}} = {{{ constantValue }}}
+{{>name_summary}} = {{{ constantValue }}}  {{!two spaces intentional}}
 {{>features}}
 
 {{>documentation}}
+
 {{>source_code}}
 {{/self}}
 

diff --git a/lib/templates/md/top_level_property.md b/lib/templates/md/top_level_property.md
index 07cd76e..3a06ef7 100644
--- a/lib/templates/md/top_level_property.md
+++ b/lib/templates/md/top_level_property.md

@@ -7,10 +7,11 @@
 {{>categorization}}
 
 {{#hasNoGetterSetter}}
-{{{ linkedReturnType }}} {{>name_summary}}
+{{{ linkedReturnType }}} {{>name_summary}}  {{!two spaces intentional}}
 {{>features}}
 
 {{>documentation}}
+
 {{>source_code}}
 {{/hasNoGetterSetter}}
 

diff --git a/lib/templates/md/typedef.md b/lib/templates/md/typedef.md
index 2800d85..3636e88 100644
--- a/lib/templates/md/typedef.md
+++ b/lib/templates/md/typedef.md

@@ -11,6 +11,7 @@
 {{>callable_multiline}}
 
 {{>documentation}}
+
 {{>source_code}}
 {{/typeDef}}