1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// Examples can assume:
6// class Cat { }
7
8/// A category with which to annotate a class, for documentation
9/// purposes.
10///
11/// A category is usually represented as a section and a subsection, each
12/// of which is a string. The engineering team that owns the library to which
13/// the class belongs defines the categories used for classes in that library.
14/// For example, the Flutter engineering team has defined categories like
15/// "Basic/Buttons" and "Material Design/Buttons" for Flutter widgets.
16///
17/// A class can have multiple categories.
18///
19/// {@tool snippet}
20///
21/// ```dart
22/// /// A copper coffee pot, as desired by Ben Turpin.
23/// /// ...documentation...
24/// @Category(<String>['Pots', 'Coffee'])
25/// @Category(<String>['Copper', 'Cookware'])
26/// @DocumentationIcon('https://example.com/images/coffee.png')
27/// @Summary('A proper cup of coffee is made in a proper copper coffee pot.')
28/// class CopperCoffeePot {
29/// // ...code...
30/// }
31/// ```
32/// {@end-tool}
33///
34/// See also:
35///
36/// * [DocumentationIcon], which is used to give the URL to an image that
37/// represents the class.
38/// * [Summary], which is used to provide a one-line description of a
39/// class that overrides the inline documentations' own description.
40class Category {
41 /// Create an annotation to provide a categorization of a class.
42 const Category(this.sections);
43
44 /// The strings the correspond to the section and subsection of the
45 /// category represented by this object.
46 ///
47 /// By convention, this list usually has two items. The allowed values
48 /// are defined by the team that owns the library to which the annotated
49 /// class belongs.
50 final List<String> sections;
51}
52
53/// A class annotation to provide a URL to an image that represents the class.
54///
55/// Each class should only have one [DocumentationIcon].
56///
57/// {@tool snippet}
58///
59/// ```dart
60/// /// Utility class for beginning a dream-sharing sequence.
61/// /// ...documentation...
62/// @Category(<String>['Military Technology', 'Experimental'])
63/// @DocumentationIcon('https://docs.example.org/icons/top.png')
64/// class DreamSharing {
65/// // ...code...
66/// }
67/// ```
68/// {@end-tool}
69///
70/// See also:
71///
72/// * [Category], to help place the class in an index.
73/// * [Summary], which is used to provide a one-line description of a
74/// class that overrides the inline documentations' own description.
75class DocumentationIcon {
76 /// Create an annotation to provide a URL to an image describing a class.
77 const DocumentationIcon(this.url);
78
79 /// The URL to an image that represents the annotated class.
80 final String url;
81}
82
83/// An annotation that provides a short description of a class for use
84/// in an index.
85///
86/// Usually the first paragraph of the documentation for a class can be used
87/// for this purpose, but on occasion the first paragraph is either too short
88/// or too long for use in isolation, without the remainder of the documentation.
89///
90/// {@tool snippet}
91///
92/// ```dart
93/// /// A famous cat.
94/// ///
95/// /// Instances of this class can hunt small animals.
96/// /// This cat has three legs.
97/// @Category(<String>['Animals', 'Cats'])
98/// @Category(<String>['Cute', 'Pets'])
99/// @DocumentationIcon('https://www.examples.net/docs/images/icons/pillar.jpeg')
100/// @Summary('A famous three-legged cat.')
101/// class Pillar extends Cat {
102/// // ...code...
103/// }
104/// ```
105/// {@end-tool}
106///
107/// See also:
108///
109/// * [Category], to help place the class in an index.
110/// * [DocumentationIcon], which is used to give the URL to an image that
111/// represents the class.
112class Summary {
113 /// Create an annotation to provide a short description of a class.
114 const Summary(this.text);
115
116 /// The text of the summary of the annotated class.
117 final String text;
118}
119