From 13f8eb39bd45bf649418de02ed36792782db6268 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Fri, 3 Nov 2023 21:50:21 +0000 Subject: [PATCH 1/3] Remove @image directive. --- README.md | 7 ++--- lib/src/generator/generator_utils.dart | 1 - .../templates.runtime_renderers.dart | 28 ------------------- lib/src/model/directives/categorization.dart | 19 ++----------- lib/src/model/documentation_comment.dart | 1 - 5 files changed, 4 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index d8e22b6b13..132236e7d0 100644 --- a/README.md +++ b/README.md @@ -215,16 +215,14 @@ 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`, and `@image` are understood and saved into this json. -Future versions of dartdoc may make direct use of the image tags. +`@category`, and `@subCategory` are understood and saved into this json. As an example, if we document the class Icon in flutter using the following: ```dart /// {@category Basics} -/// {@category Assets, Images, and Icons} +/// {@category Assets, and Icons} /// {@subCategory Information displays} -/// {@image } class Icon extends StatelessWidget {} ``` @@ -243,7 +241,6 @@ that will result in the following json: "subcategories": [ "Information displays" ], - "image": "" } ``` diff --git a/lib/src/generator/generator_utils.dart b/lib/src/generator/generator_utils.dart index acacfdfe20..73ba95edbd 100644 --- a/lib/src/generator/generator_utils.dart +++ b/lib/src/generator/generator_utils.dart @@ -24,7 +24,6 @@ String generateCategoryJson(Iterable categories, bool pretty) { 'categories': categorization.categoryNames, if (categorization.hasSubCategoryNames) 'subcategories': categorization.subCategoryNames, - if (categorization.hasImage) 'image': categorization.image, } ]; diff --git a/lib/src/generator/templates.runtime_renderers.dart b/lib/src/generator/templates.runtime_renderers.dart index efc8fa7104..9c5b624e13 100644 --- a/lib/src/generator/templates.runtime_renderers.dart +++ b/lib/src/generator/templates.runtime_renderers.dart @@ -966,13 +966,6 @@ class _Renderer_Categorization extends RendererBase { self.renderSimpleVariable(c, remainingNames, 'bool'), getBool: (CT_ c) => c.hasCategoryNames == true, ), - 'hasImage': Property( - getValue: (CT_ c) => c.hasImage, - renderVariable: (CT_ c, Property self, - List remainingNames) => - self.renderSimpleVariable(c, remainingNames, 'bool'), - getBool: (CT_ c) => c.hasImage == true, - ), 'hasSubCategoryNames': Property( getValue: (CT_ c) => c.hasSubCategoryNames, renderVariable: (CT_ c, Property self, @@ -980,27 +973,6 @@ class _Renderer_Categorization extends RendererBase { self.renderSimpleVariable(c, remainingNames, 'bool'), getBool: (CT_ c) => c.hasSubCategoryNames == true, ), - 'image': Property( - getValue: (CT_ c) => c.image, - 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.image == null, - renderValue: (CT_ c, RendererBase r, - List ast, StringSink sink) { - _render_String(c.image!, 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 2e68842474..ebedbd5f40 100644 --- a/lib/src/model/directives/categorization.dart +++ b/lib/src/model/directives/categorization.dart @@ -6,9 +6,8 @@ import 'package:collection/collection.dart'; import 'package:dartdoc/src/model/model.dart'; import 'package:meta/meta.dart'; -final RegExp _categoryRegExp = RegExp( - r'[ ]*{@(category|subCategory|image) (.+?)}[ ]*\n?', - multiLine: true); +final RegExp _categoryRegExp = + RegExp(r'[ ]*{@(category|subCategory) (.+?)}[ ]*\n?', multiLine: true); /// Mixin parsing the `@category` directive for ModelElements. mixin Categorization on DocumentationComment implements Indexable { @@ -31,15 +30,12 @@ mixin Categorization on DocumentationComment implements Indexable { categorySet.add(match[2]!.trim()); case 'subCategory': subCategorySet.add(match[2]!.trim()); - case 'image': - _image = match[2]!.trim(); } return ''; }); _categoryNames = categorySet.toList(growable: false)..sort(); _subCategoryNames = subCategorySet.toList(growable: false)..sort(); - _image ??= ''; return rawDocs; } @@ -65,17 +61,6 @@ mixin Categorization on DocumentationComment implements Indexable { return _categoryNames; } - bool get hasImage => image!.isNotEmpty; - String? _image; - - /// Either a URI to a defined image, - /// or 'null' if one was not declared. - String? get image { - // TODO(jcollins-g): avoid side-effect dependency - if (_image == null) documentationLocal; - return _image; - } - @visibleForTesting List get categories => [ ...?categoryNames?.map((n) => package.nameToCategory[n]).whereNotNull() diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index fe893a607b..7638e5dd22 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -161,7 +161,6 @@ mixin DocumentationComment 'canonicalFor', 'category', 'hideConstantImplementations', - 'image', 'subCategory', // Common Dart annotations which may decorate named parameters: From 126a5f43c2cdda3291a66ab5a8280a999bbe1d8b Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Mon, 6 Nov 2023 19:22:14 +0000 Subject: [PATCH 2/3] Change README to have quotes. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 132236e7d0..fb6fe039de 100644 --- a/README.md +++ b/README.md @@ -221,8 +221,8 @@ As an example, if we document the class Icon in flutter using the following: ```dart /// {@category Basics} -/// {@category Assets, and Icons} -/// {@subCategory Information displays} +/// {@category "Assets and Icons"} +/// {@subCategory "Information displays"} class Icon extends StatelessWidget {} ``` @@ -235,7 +235,7 @@ that will result in the following json: "href": "widgets/Icon-class.html", "type": "class", "categories": [ - "Assets, Images, and Icons", + "Assets and Icons", "Basics" ], "subcategories": [ From e6d4464e0b046c649d7e59305883bdc6b9010282 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Mon, 6 Nov 2023 19:27:57 +0000 Subject: [PATCH 3/3] Remove quotes. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fb6fe039de..c305102bc7 100644 --- a/README.md +++ b/README.md @@ -221,8 +221,8 @@ As an example, if we document the class Icon in flutter using the following: ```dart /// {@category Basics} -/// {@category "Assets and Icons"} -/// {@subCategory "Information displays"} +/// {@category Assets and Icons} +/// {@subCategory Information displays} class Icon extends StatelessWidget {} ```