Remove @samples directive. (#3567)

Author: kallentu

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:
 

lib/src/generator/generator_utils.dart

@@ -25,7 +25,6 @@ String generateCategoryJson(Iterable<Categorization> categories, bool pretty) {
         if (categorization.hasSubCategoryNames)
           'subcategories': categorization.subCategoryNames,
         if (categorization.hasImage) 'image': categorization.image,
-        if (categorization.hasSamples) 'samples': categorization.samples,
       }
   ];
 

lib/src/generator/templates.runtime_renderers.dart

@@ -973,13 +973,6 @@ class _Renderer_Categorization extends RendererBase<Categorization> {
                       self.renderSimpleVariable(c, remainingNames, 'bool'),
                   getBool: (CT_ c) => c.hasImage == true,
                 ),
-                'hasSamples': Property(
-                  getValue: (CT_ c) => c.hasSamples,
-                  renderVariable: (CT_ c, Property<CT_> self,
-                          List<String> remainingNames) =>
-                      self.renderSimpleVariable(c, remainingNames, 'bool'),
-                  getBool: (CT_ c) => c.hasSamples == true,
-                ),
                 'hasSubCategoryNames': Property(
                   getValue: (CT_ c) => c.hasSubCategoryNames,
                   renderVariable: (CT_ c, Property<CT_> self,
@@ -1008,28 +1001,6 @@ class _Renderer_Categorization extends RendererBase<Categorization> {
                     _render_String(c.image!, ast, r.template, sink, parent: r);
                   },
                 ),
-                'samples': Property(
-                  getValue: (CT_ c) => c.samples,
-                  renderVariable:
-                      (CT_ c, Property<CT_> self, List<String> 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<CT_> r,
-                      List<MustachioNode> ast, StringSink sink) {
-                    _render_String(c.samples!, ast, r.template, sink,
-                        parent: r);
-                  },
-                ),
                 'subCategoryNames': Property(
                   getValue: (CT_ c) => c.subCategoryNames,
                   renderVariable: (CT_ c, Property<CT_> self,

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,16 +33,13 @@ mixin Categorization on DocumentationComment implements Indexable {
           subCategorySet.add(match[2]!.trim());
         case 'image':
           _image = match[2]!.trim();
-        case 'samples':
-          _samples = match[2]!.trim();
       }
       return '';
     });
 
     _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<Category> 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;

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: