From 55c4f451bf55478ae0d056b9ebdd3d180e2ff090 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Fri, 3 Nov 2023 01:10:18 +0000 Subject: [PATCH] Remove @samples directive. --- README.md | 4 +-- lib/src/generator/generator_utils.dart | 1 - .../templates.runtime_renderers.dart | 29 ------------------- lib/src/model/directives/categorization.dart | 18 ++---------- lib/src/model/documentation_comment.dart | 1 - 5 files changed, 4 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index b426965aa6..d8e22b6b13 100644 --- a/README.md +++ b/README.md @@ -215,8 +215,8 @@ library my_library; A file `categories.json` will be generated at the top level of the documentation tree with information about categories collected from objects in the source tree. The directives -`@category`, `@subCategory`, `@image`, and `@samples` are understood and saved into this json. -Future versions of dartdoc may make direct use of the image and samples tags. +`@category`, `@subCategory`, and `@image` are understood and saved into this json. +Future versions of dartdoc may make direct use of the image tags. As an example, if we document the class Icon in flutter using the following: diff --git a/lib/src/generator/generator_utils.dart b/lib/src/generator/generator_utils.dart index bf57172443..acacfdfe20 100644 --- a/lib/src/generator/generator_utils.dart +++ b/lib/src/generator/generator_utils.dart @@ -25,7 +25,6 @@ String generateCategoryJson(Iterable categories, bool pretty) { if (categorization.hasSubCategoryNames) 'subcategories': categorization.subCategoryNames, if (categorization.hasImage) 'image': categorization.image, - if (categorization.hasSamples) 'samples': categorization.samples, } ]; diff --git a/lib/src/generator/templates.runtime_renderers.dart b/lib/src/generator/templates.runtime_renderers.dart index ecb08d0869..efc8fa7104 100644 --- a/lib/src/generator/templates.runtime_renderers.dart +++ b/lib/src/generator/templates.runtime_renderers.dart @@ -973,13 +973,6 @@ class _Renderer_Categorization extends RendererBase { self.renderSimpleVariable(c, remainingNames, 'bool'), getBool: (CT_ c) => c.hasImage == true, ), - 'hasSamples': Property( - getValue: (CT_ c) => c.hasSamples, - renderVariable: (CT_ c, Property self, - List remainingNames) => - self.renderSimpleVariable(c, remainingNames, 'bool'), - getBool: (CT_ c) => c.hasSamples == true, - ), 'hasSubCategoryNames': Property( getValue: (CT_ c) => c.hasSubCategoryNames, renderVariable: (CT_ c, Property self, @@ -1008,28 +1001,6 @@ class _Renderer_Categorization extends RendererBase { _render_String(c.image!, ast, r.template, sink, parent: r); }, ), - 'samples': Property( - getValue: (CT_ c) => c.samples, - renderVariable: - (CT_ c, Property self, List remainingNames) { - if (remainingNames.isEmpty) { - return self.getValue(c).toString(); - } - var name = remainingNames.first; - var nextProperty = - _Renderer_String.propertyMap().getValue(name); - return nextProperty.renderVariable( - self.getValue(c) as String, - nextProperty, - [...remainingNames.skip(1)]); - }, - isNullValue: (CT_ c) => c.samples == null, - renderValue: (CT_ c, RendererBase r, - List ast, StringSink sink) { - _render_String(c.samples!, ast, r.template, sink, - parent: r); - }, - ), 'subCategoryNames': Property( getValue: (CT_ c) => c.subCategoryNames, renderVariable: (CT_ c, Property self, diff --git a/lib/src/model/directives/categorization.dart b/lib/src/model/directives/categorization.dart index 879308ef10..2e68842474 100644 --- a/lib/src/model/directives/categorization.dart +++ b/lib/src/model/directives/categorization.dart @@ -7,7 +7,7 @@ import 'package:dartdoc/src/model/model.dart'; import 'package:meta/meta.dart'; final RegExp _categoryRegExp = RegExp( - r'[ ]*{@(category|subCategory|image|samples) (.+?)}[ ]*\n?', + r'[ ]*{@(category|subCategory|image) (.+?)}[ ]*\n?', multiLine: true); /// Mixin parsing the `@category` directive for ModelElements. @@ -33,8 +33,6 @@ mixin Categorization on DocumentationComment implements Indexable { subCategorySet.add(match[2]!.trim()); case 'image': _image = match[2]!.trim(); - case 'samples': - _samples = match[2]!.trim(); } return ''; }); @@ -42,7 +40,6 @@ mixin Categorization on DocumentationComment implements Indexable { _categoryNames = categorySet.toList(growable: false)..sort(); _subCategoryNames = subCategorySet.toList(growable: false)..sort(); _image ??= ''; - _samples ??= ''; return rawDocs; } @@ -79,17 +76,6 @@ mixin Categorization on DocumentationComment implements Indexable { return _image; } - bool get hasSamples => samples?.isNotEmpty ?? false; - String? _samples; - - /// Either a URI to documentation with samples, - /// or 'null' if one was not declared. - String? get samples { - // TODO(jcollins-g): avoid side-effect dependency - if (_samples == null) documentationLocal; - return _samples; - } - @visibleForTesting List get categories => [ ...?categoryNames?.map((n) => package.nameToCategory[n]).whereNotNull() @@ -102,7 +88,7 @@ mixin Categorization on DocumentationComment implements Indexable { bool? _hasCategorization; - /// True if categories, subcategories, a documentation icon, or samples were + /// True if categories, subcategories, or a documentation icon were /// declared. late final bool hasCategorization = () { if (_hasCategorization == null) documentationLocal; diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index 9635a88486..fe893a607b 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -162,7 +162,6 @@ mixin DocumentationComment 'category', 'hideConstantImplementations', 'image', - 'samples', 'subCategory', // Common Dart annotations which may decorate named parameters: