mirror of
https://github.com/flutter/flutter.git
synced 2026-02-20 02:29:02 +08:00
8f56f6fdd1
Mainly, this adds documentation to members that were previously lacking documentation. It also adds a big block of documentation about improving performance of widgets. This also removes some references to package:collection and adds global setEquals and listEquals methods in foundation that we can use. (setEquals in particular should be much faster than the package:collection equivalent, though both should be faster as they avoid allocating new objects.) All remaining references now qualify the import so we know what our remaining dependencies are. Also lots of code reordering in Flutter driver to make the code consistent and apply the style guide more thoroughly.
113 lines
3.8 KiB
Dart
113 lines
3.8 KiB
Dart
// Copyright 2017 The Chromium Authors. All rights reserved.
|
|
// Use of this source code is governed by a BSD-style license that can be
|
|
// found in the LICENSE file.
|
|
|
|
/// 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.
|
|
///
|
|
/// ## Sample code
|
|
///
|
|
/// ```dart
|
|
/// /// A copper coffee pot, as desired by Ben Turpin.
|
|
/// /// ...documentation...
|
|
/// @Category(const <String>['Pots', 'Coffee'])
|
|
/// @Category(const <String>['Copper', 'Cookware'])
|
|
/// @DocumentationIcon('https://example.com/images/coffee.png')
|
|
/// @Summary('A proper cup of coffee is made in a proper copper coffee pot.')
|
|
/// class CopperCoffeePot {
|
|
/// // ...code...
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// 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 {
|
|
/// Create an annotation to provide a categorization of a class.
|
|
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].
|
|
///
|
|
/// ## Sample code
|
|
///
|
|
/// ```dart
|
|
/// /// Utility class for beginning a dream-sharing sequence.
|
|
/// /// ...documentation...
|
|
/// @Category(const <String>['Military Technology', 'Experimental'])
|
|
/// @DocumentationIcon('https://docs.example.org/icons/top.png')
|
|
/// class DreamSharing {
|
|
/// // ...code...
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// 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 {
|
|
/// Create an annotation to provide a URL to an image describing a class.
|
|
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.
|
|
///
|
|
/// ## Sample code
|
|
///
|
|
/// ```dart
|
|
/// /// A famous cat.
|
|
/// ///
|
|
/// /// Instances of this class can hunt small animals.
|
|
/// /// This cat has three legs.
|
|
/// @Category(const <String>['Animals', 'Cats'])
|
|
/// @Category(const <String>['Cute', 'Pets'])
|
|
/// @DocumentationIcon('https://www.examples.net/docs/images/icons/pillar.jpeg')
|
|
/// @Summary('A famous three-legged cat.')
|
|
/// class Pillar extends Cat {
|
|
/// // ...code...
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// 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 {
|
|
/// Create an annotation to provide a short description of a class.
|
|
const Summary(this.text) : assert(text != null);
|
|
|
|
/// The text of the summary of the annotated class.
|
|
final String text;
|
|
}
|