Docs for widgets

packages/ubuntu_desktop_installer/lib/widgets/dropdown_builder.dart

@@ -1,6 +1,29 @@
 import 'package:flutter/material.dart';
 
+/// A builder widget that makes it straight-forward to build a dropdown
+/// for an arbitrary list of values.
+///
+/// The following example creates a dropdown for choosing enum values:
+/// ```dart
+/// DropdownBuilder<MyEnum>(
+///   values: MyEnum.values,
+///   selected: model.enumValue,
+///   onSelected: (value) => model.enumValue = value,
+///   itemBuilder: (context, value, _) => Text(value.toString()),
+/// )
+/// ```
+///
+/// See also:
+///  * [MenuButtonBuilder] - A similar builder widget but for menu buttons.
 class DropdownBuilder<T> extends StatelessWidget {
+  /// Creates a dropdown with the given `values`.
+  ///
+  /// The `onSelected` callback is called when the user selects an item.
+  ///
+  /// Optionally, the currently `selected` value can be specified too.
+  ///
+  /// The `itemBuilder` function is called for each item in the dropdown menu.
+  /// The returned widgets are set as children of the dropdown menu items.
   const DropdownBuilder({
     Key? key,
     this.selected,
@@ -9,9 +32,20 @@ class DropdownBuilder<T> extends StatelessWidget {
     required this.itemBuilder,
   }) : super(key: key);
 
+  /// The currently selected value or `null` if no value is selected.
   final T? selected;
+
+  /// The list of values.
+  ///
+  /// For enums, use the enum's `values` constant.
   final List<T> values;
+
+  /// Called when the user selects an item.
   final ValueChanged<T> onSelected;
+
+  /// Builds a dropdown item for the given `value`.
+  ///
+  /// Note: The returned widget is set as a child of [DropDownMenuItem].
   final ValueWidgetBuilder<T> itemBuilder;
 
   @override

packages/ubuntu_desktop_installer/lib/widgets/localized_view.dart

@@ -1,12 +1,23 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_gen/gen_l10n/app_localizations.dart';
 
+/// The signature of the builder callback with access to localized strings.
 typedef LocalizedViewBuilder = Widget Function(
     BuildContext context, AppLocalizations lang);
 
+/// A view that provides access to localized strings.
+///
+/// Example:
+/// ```dart
+/// LocalizedView(
+///   builder: (context, lang) => Text(lang.appName),
+/// )
+/// ```
 class LocalizedView extends StatelessWidget {
+  /// A builder callback that provides access to localized strings.
   final LocalizedViewBuilder builder;
 
+  /// Creates a localized view instance with the given `builder` callback.
   LocalizedView({required this.builder});
 
   @override

packages/ubuntu_desktop_installer/lib/widgets/menu_button_builder.dart

@@ -1,6 +1,32 @@
 import 'package:flutter/material.dart';
 
+/// A builder widget that makes it straight-forward to build a menu button
+/// for an arbitrary list of values.
+///
+/// The following example creates a menu button for choosing enum values:
+/// ```dart
+/// MenuButtonBuilder<MyEnum>(
+///   values: MyEnum.values,
+///   selected: model.enumValue,
+///   onSelected: (value) => model.enumValue = value,
+///   iconBuilder: (context, value, _) => _toIcon(value),
+///   itemBuilder: (context, value, _) => Text(value.toString()),
+/// )
+/// ```
+///
+/// See also:
+///  * [DropdownBuilder] - A similar builder widget but for dropdowns.
 class MenuButtonBuilder<T> extends StatelessWidget {
+  /// Creates a menu button with the given `values`.
+  ///
+  /// The `onSelected` callback is called when the user selects an item.
+  ///
+  /// The `itemBuilder` function is called for each item in the menu.
+  /// The returned widgets are set as children of the popup menu items.
+  ///
+  /// The `iconBuilder` function is called for the selected item. The returned
+  /// widget is set as an icon of the menu button.
+  ///
   const MenuButtonBuilder({
     Key? key,
     required this.selected,
@@ -10,10 +36,25 @@ class MenuButtonBuilder<T> extends StatelessWidget {
     required this.itemBuilder,
   }) : super(key: key);
 
+  /// The currently selected value.
   final T selected;
+
+  /// The list of values.
+  ///
+  /// For enums, use the enum's `values` constant.
   final List<T> values;
+
+  /// Called when the user selects an item.
   final ValueChanged<T> onSelected;
+
+  /// Builds an icon for the given `value`.
+  ///
+  /// Note: The returned widget is set as an icon of [PopupMenuButton].
   final ValueWidgetBuilder<T> iconBuilder;
+
+  /// Builds a menu item for the given `value`.
+  ///
+  /// Note: The returned widget is set as a child of [CheckedPopupMenuItem].
   final ValueWidgetBuilder<T> itemBuilder;
 
   @override

packages/ubuntu_desktop_installer/lib/widgets/option_card.dart

@@ -1,6 +1,30 @@
 import 'package:flutter/material.dart';
 
+/// A card widget that presents a toggleable option.
+///
+/// For example:
+/// ```dart
+/// Row(
+///   children: [
+///     OptionCard(
+///       imageAsset: 'assets/foo.png',
+///       titleText: 'Foo',
+///       bodyText: 'Description...',
+///       selected: model.option == MyOption.foo,
+///       onSelected: () => model.option = Option.foo,
+///     ),
+///     OptionCard(
+///       imageAsset: 'assets/bar.png',
+///       titleText: 'Bar',
+///       bodyText: 'Description...',
+///       selected: model.option == MyOption.bar,
+///       onSelected: () => model.option = MyOption.bar,
+///     ),
+///   ],
+/// )
+/// ```
 class OptionCard extends StatefulWidget {
+  /// Creates an option card with the given properties.
   const OptionCard({
     Key? key,
     this.imageAsset,
@@ -10,19 +34,30 @@ class OptionCard extends StatefulWidget {
     required this.onSelected,
   }) : super(key: key);
 
+  /// An image asset that illustrates the option.
   final String? imageAsset;
+
+  /// A short title below the image.
   final String? titleText;
+
+  /// A longer descriptive body text below the title.
   final String? bodyText;
+
+  /// Whether the option is currently selected.
   final bool selected;
+
+  /// Called when the option is selected.
   final VoidCallback onSelected;
 
   @override
   OptionCardState createState() => OptionCardState();
 }
 
+@visibleForTesting
+// ignore: public_member_api_docs
 class OptionCardState extends State<OptionCard> {
   bool _hovered = false;
-  bool get hovered => _hovered;
+  bool get hovered => _hovered; // ignore: public_member_api_docs
 
   void _setHovered(bool hovered) {
     if (_hovered == hovered) return;