annotations.dart 3.9 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5 6 7
// Examples can assume:
// class Cat { }

8 9 10 11 12 13 14 15 16 17 18
/// A category with which to annotate a class, for documentation
/// purposes.
///
/// A category is usually represented as a section and a subsection, each
/// of which is a string. The engineering team that owns the library to which
/// the class belongs defines the categories used for classes in that library.
/// For example, the Flutter engineering team has defined categories like
/// "Basic/Buttons" and "Material Design/Buttons" for Flutter widgets.
///
/// A class can have multiple categories.
///
19
/// {@tool snippet}
20 21 22 23
///
/// ```dart
/// /// A copper coffee pot, as desired by Ben Turpin.
/// /// ...documentation...
24 25
/// @Category(<String>['Pots', 'Coffee'])
/// @Category(<String>['Copper', 'Cookware'])
26 27 28 29 30 31
/// @DocumentationIcon('https://example.com/images/coffee.png')
/// @Summary('A proper cup of coffee is made in a proper copper coffee pot.')
/// class CopperCoffeePot {
///   // ...code...
/// }
/// ```
32
/// {@end-tool}
33 34 35 36 37 38 39 40
///
/// See also:
///
///  * [DocumentationIcon], which is used to give the URL to an image that
///    represents the class.
///  * [Summary], which is used to provide a one-line description of a
///    class that overrides the inline documentations' own description.
class Category {
41
  /// Create an annotation to provide a categorization of a class.
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
  const Category(this.sections) : assert(sections != null);

  /// The strings the correspond to the section and subsection of the
  /// category represented by this object.
  ///
  /// By convention, this list usually has two items. The allowed values
  /// are defined by the team that owns the library to which the annotated
  /// class belongs.
  final List<String> sections;
}

/// A class annotation to provide a URL to an image that represents the class.
///
/// Each class should only have one [DocumentationIcon].
///
57
/// {@tool snippet}
58 59 60 61
///
/// ```dart
/// /// Utility class for beginning a dream-sharing sequence.
/// /// ...documentation...
62
/// @Category(<String>['Military Technology', 'Experimental'])
63 64 65 66 67
/// @DocumentationIcon('https://docs.example.org/icons/top.png')
/// class DreamSharing {
///   // ...code...
/// }
/// ```
68
/// {@end-tool}
69 70 71 72 73 74 75
///
/// See also:
///
///  * [Category], to help place the class in an index.
///  * [Summary], which is used to provide a one-line description of a
///    class that overrides the inline documentations' own description.
class DocumentationIcon {
76
  /// Create an annotation to provide a URL to an image describing a class.
77 78 79 80 81 82 83 84 85 86 87 88 89
  const DocumentationIcon(this.url) : assert(url != null);

  /// The URL to an image that represents the annotated class.
  final String url;
}

/// An annotation that provides a short description of a class for use
/// in an index.
///
/// Usually the first paragraph of the documentation for a class can be used
/// for this purpose, but on occasion the first paragraph is either too short
/// or too long for use in isolation, without the remainder of the documentation.
///
90
/// {@tool snippet}
91 92 93 94 95 96
///
/// ```dart
/// /// A famous cat.
/// ///
/// /// Instances of this class can hunt small animals.
/// /// This cat has three legs.
97 98
/// @Category(<String>['Animals', 'Cats'])
/// @Category(<String>['Cute', 'Pets'])
99 100 101 102 103 104
/// @DocumentationIcon('https://www.examples.net/docs/images/icons/pillar.jpeg')
/// @Summary('A famous three-legged cat.')
/// class Pillar extends Cat {
///   // ...code...
/// }
/// ```
105
/// {@end-tool}
106 107 108 109 110 111 112
///
/// See also:
///
///  * [Category], to help place the class in an index.
///  * [DocumentationIcon], which is used to give the URL to an image that
///    represents the class.
class Summary {
113
  /// Create an annotation to provide a short description of a class.
114 115 116 117 118
  const Summary(this.text) : assert(text != null);

  /// The text of the summary of the annotated class.
  final String text;
}