docs(ui_layout): add some documentation + readme

2023-04-13 23:29:27 +02:00
parent 56de994e67
commit 79c5aa7c76
9 changed files with 69 additions and 97 deletions
@@ -18,7 +18,12 @@ import 'package:flutter/material.dart';
 import 'package:gap/gap.dart';
 import 'package:wyatt_ui_layout/src/presentation/layouts/layout.dart';

+/// {@template grid_layout}
+/// A concrete implementation of the [ContentLayout] abstract class for a layout
+/// which defines a layout structure with a grid layout.
+/// {@endtemplate}
 class GridLayout extends ContentLayout {
+  /// {@macro grid_layout}
  const GridLayout({
    required this.children,
    this.verticalGap = 30,
@@ -26,8 +31,13 @@ class GridLayout extends ContentLayout {
    super.key,
  });

+  /// The children of the layout.
  final List<Widget> children;
+
+  /// The vertical gap between the children.
  final double verticalGap;
+
+  /// The horizontal gap between the children.
  final double horizontalGap;

  @override
@@ -1,4 +1,4 @@
-// Copyright (C) 2022 WYATT GROUP
+// Copyright (C) 2023 WYATT GROUP
 // Please see the AUTHORS file for details.
 //
 // This program is free software: you can redistribute it and/or modify
@@ -14,28 +14,35 @@
 // You should have received a copy of the GNU General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.

-/// This file contains the [Layout] abstract class, which provides a base
-/// for creating custom layout widgets in Flutter.
-import 'package:flutter/material.dart';
+import 'package:flutter/widgets.dart';

+/// {@template layout}
 /// An abstract class that provides a base for creating custom layout widgets.
 ///
 /// This class can be used as a base for creating custom layout widgets in
 /// Flutter. It extends the [StatelessWidget] class and adds support for
 /// providing a custom key. Custom layout widgets that extend this class should
 /// override the [build] method to define the layout.
+/// {@endtemplate}
 abstract class Layout extends StatelessWidget {
-  /// Creates a new [Layout] instance.
-  ///
-  /// [key] is an optional parameter that can be used to provide a custom key
-  /// for the widget.
+  /// {@macro layout}
  const Layout({super.key});
 }

+/// {@template structural_layout}
+/// An abstract class that provides a base for creating custom structural layout
+/// widgets.
+/// {@endtemplate}
 abstract class StructuralLayout extends Layout {
+  /// {@macro structural_layout}
  const StructuralLayout({super.key});
 }

+/// {@template content_layout}
+/// An abstract class that provides a base for creating custom content layout
+/// widgets.
+/// {@endtemplate}
 abstract class ContentLayout extends Layout {
+  /// {@macro content_layout}
  const ContentLayout({super.key});
 }
@@ -14,34 +14,27 @@
 // You should have received a copy of the GNU General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.

-/// This file contains the concrete class [BottomNavigationBarLayout].
-///
-/// The [BottomNavigationBarLayout] class is a concrete implementation of the
-/// [Layout] abstract class, which defines a layout structure with a bottom
-/// navigation bar component.
-///
-/// [BottomNavigationBarLayout] includes an optional
-/// [BottomNavigationBarLayout.custom]
-/// function for customizing the bottom navigation bar component.
 import 'package:flutter/material.dart';
 import 'package:wyatt_ui_components/wyatt_ui_components.dart';
 import 'package:wyatt_ui_layout/src/presentation/layouts/layout.dart';

-/// A concrete implementation of the [Layout] abstract class for a layout with
-/// a bottom navigation bar component.
+/// {@template bottom_navigation_bar_layout}
+/// A concrete implementation of the [Layout] abstract class for a layout which
+/// defines a layout structure with a bottom navigation bar component.
+/// {@endtemplate}
 class BottomNavigationBarLayout extends StructuralLayout {
-  /// Creates a [BottomNavigationBarLayout] instance.
-  ///
-  /// [body] represents the main content of the layout.
-  /// [custom] is an optional function that can be used to customize
-  /// the bottom navigation bar component.
+  /// {@macro bottom_navigation_bar_layout}
  const BottomNavigationBarLayout({
    required this.body,
    this.custom,
    super.key,
  });

+  /// The main content of the layout.
  final Widget? body;
+
+  /// An optional function that can be used to customize the bottom navigation
+  /// bar component.
  final BottomNavigationBarComponent? Function(BottomNavigationBarComponent?)?
      custom;

@@ -18,6 +18,7 @@ import 'package:flutter/material.dart';
 import 'package:wyatt_ui_components/wyatt_ui_components.dart';
 import 'package:wyatt_ui_layout/src/presentation/layouts/layout.dart';

+/// {@template frame_layout}
 /// A layout that contains a top app bar, a body and a bottom navigation bar.
 ///
 /// This layout consists of a [TopAppBarComponent] at the top of the screen,
@@ -25,15 +26,9 @@ import 'package:wyatt_ui_layout/src/presentation/layouts/layout.dart';
 /// You can customize the app bar and the bottom navigation bar by passing
 /// a [customAppBar] and a [customBottomNavBar] functions that take
 /// the corresponding components and return the customized ones.
+/// {@endtemplate}
 class FrameLayout extends StructuralLayout {
-  /// Creates a [FrameLayout] instance.
-  ///
-  /// [body] represents the main content of the layout.
-  /// [customAppBar] is an optional function that can be used to customize
-  ///  the top app bar component.
-  /// [customBottomNavBar] is an optional function that can be used to customize
-  ///  the bottom navigation bar component.
-  /// [height] represents the height of the top app bar.
+  /// {@macro frame_layout}
  const FrameLayout({
    required this.body,
    this.customAppBar,
@@ -42,10 +37,17 @@ class FrameLayout extends StructuralLayout {
    super.key,
  });

+  /// An optional function that can be used to customize the top app bar
  final TopAppBarComponent? Function(TopAppBarComponent?)? customAppBar;
+
+  /// An optional function that can be used to customize the bottom navigation
  final BottomNavigationBarComponent? Function(BottomNavigationBarComponent?)?
      customBottomNavBar;
+
+  /// The main content of the layout.
  final Widget body;
+
+  /// The height of the top app bar.
  final double height;

  @override
@@ -14,16 +14,11 @@
 // You should have received a copy of the GNU General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.

-/// This file contains the abstract class [TopBarLayout] and two concrete
-/// classes [TopAppBarLayout] and [TopNavigationBarLayout].
-/// The [TopBarLayout] abstract class defines a layout structure with a top bar.
-/// The [TopAppBarLayout] and [TopNavigationBarLayout] classes are concrete
-///  implementations of the [TopBarLayout] class.
-
 import 'package:flutter/material.dart';
 import 'package:wyatt_ui_components/wyatt_ui_components.dart';
 import 'package:wyatt_ui_layout/src/presentation/layouts/layout.dart';

+/// {@template top_bar_layout}
 /// An abstract class for creating layouts with a top bar component.
 ///
 /// This class provides a base for creating layouts that include a top bar
@@ -34,14 +29,10 @@ import 'package:wyatt_ui_layout/src/presentation/layouts/layout.dart';
 /// given [BuildContext].
 ///
 /// [T] represents the type of the top bar component.
+/// {@endtemplate}
 abstract class TopBarLayout<T extends TopBarComponent>
    extends StructuralLayout {
-  /// Creates a [TopBarLayout] instance.
-  ///
-  /// [body] represents the main content of the layout.
-  /// [custom] is an optional function that can be used to customize
-  ///  the top bar component.
-  /// [height] represents the height of the top bar.
+  /// {@macro top_bar_layout}
  const TopBarLayout({
    required this.body,
    this.custom,
@@ -49,9 +40,15 @@ abstract class TopBarLayout<T extends TopBarComponent>
    super.key,
  });

+  /// The main content of the layout.
  final Widget body;

+  /// An optional function that can be used to customize the top bar component.
+  /// The function takes the top bar component as an argument and returns
+  /// a customized top bar component.
  final T? Function(T?)? custom;
+
+  /// The height of the top bar.
  final double height;

  /// Returns the top bar component for the given [BuildContext].
@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.

-/// Wyatt Ui Layout
+/// Wyatt UI Layout
 library wyatt_ui_layout;

 export 'src/src.dart';