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. |
40 | class 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. |
75 | class 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. |
112 | class 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 | |