fix: [MDS-942] Improve documentation (#340)

Co-authored-by: Birgitt Majas <birgitt.majas@yolo.com>

README.md

@@ -53,7 +53,7 @@ final lightTheme = ThemeData.light().copyWith(
 
 ```dart
 return MaterialApp(
-      title: 'MDS example',
+      title: 'Moon Design System example',
       theme: lightTheme,
       home: const HomePage(),
  );

example/assets/code_snippets/accordion.md

@@ -23,7 +23,7 @@ class _AccordionState extends State<Accordion> {
     return Column(
       children: [
         MoonAccordion<AccordionItems>(
-          // identityValue and groupIdentityValue can be used to control the 
+          // The identityValue and groupIdentityValue can be used to control the 
           // auto collapse behaviour of the accordion.
           identityValue: AccordionItems.first,
           groupIdentityValue: _currentlyOpenAccordionItem,
@@ -39,7 +39,7 @@ class _AccordionState extends State<Accordion> {
           ],
         ),
         MoonAccordion<AccordionItems>(
-          // identityValue and groupIdentityValue can be used to control the 
+          // The identityValue and groupIdentityValue can be used to control the 
           // auto collapse behaviour of the accordion.
           identityValue: AccordionItems.second,
           groupIdentityValue: _currentlyOpenAccordionItem,

example/assets/code_snippets/auth_code.md

@@ -10,7 +10,7 @@ class AuthCode extends StatelessWidget {
       height: 95, // To avoid widget jumping with error text, use a fixed-height wrapper.
       child: MoonAuthCode(
         validator: (String? pin) {
-          // Matches all numbers
+          // Matches all numbers.
           final RegExp regex = RegExp(r'^\d+$');
 
           return pin != null && pin.length == 4 && !regex.hasMatch(pin)

example/assets/code_snippets/bottom_sheet.md

@@ -13,7 +13,7 @@ class BottomSheet extends StatelessWidget {
         height: MediaQuery.of(context).size.height * 0.7,
         builder: (BuildContext context) => Column(
           children: [
-            // Drag handle for the bottom sheet
+            // Drag handle for the bottom sheet.
             Container(
               height: 4,
               width: 40,

example/assets/code_snippets/drawer.md

@@ -21,7 +21,7 @@ class Drawer extends StatelessWidget {
             return Center(
               child: MoonFilledButton(
                 onTap: () => Scaffold.of(context).openDrawer(),
-                label: const Text("Open drawer"),
+                label: const Text("Open MoonDrawer"),
               ),
             );
           },

example/assets/code_snippets/dropdown.md

@@ -26,7 +26,7 @@ class _DropdownState extends State<Dropdown> {
   Widget build(BuildContext context) {
     return Column(
       children: [
-        //Dropdown with multiple choices
+        // MoonDropdown with multiple choices.
         MoonDropdown(
           show: _showChoices,
           constrainWidthToChild: true,
@@ -82,7 +82,7 @@ class _DropdownState extends State<Dropdown> {
           ),
         ),
 
-        // Dropdown as menu
+        // MoonDropdown as a menu.
         MoonDropdown(
           show: _showMenu,
           groupId: _groupId,

example/assets/code_snippets/tab_bar.md

@@ -63,7 +63,7 @@ class _TabBarState extends State<TabBar> with SingleTickerProviderStateMixin {
           ],
         ),
 
-        // MoonTabBar with TabBarView
+        // MoonTabBar with TabBarView.
         MoonTabBar(
           isExpanded: true,
           tabController: tabController,

example/assets/code_snippets/toast.md

@@ -11,7 +11,7 @@ class Toast extends StatelessWidget {
         context,
         label: const Text('This is MoonToast'),
       ),
-      label: const Text("Show toast"),
+      label: const Text("Show MoonToast"),
     );
   }
 }

example/assets/code_snippets/tooltip.md

@@ -19,7 +19,7 @@ class _TooltipState extends State<Tooltip> {
       child: MoonFilledButton(
         buttonSize: MoonButtonSize.sm,
         onTap: () => setState(() => showOnTap = true),
-        label: const Text("Show tooltip"),
+        label: const Text("Show MoonTooltip"),
       ),
     );
   }

example/lib/src/storybook/common/color_options.dart

@@ -3,10 +3,10 @@ import 'package:flutter/material.dart';
 import 'package:moon_design/moon_design.dart';
 import 'package:storybook_flutter/storybook_flutter.dart';
 
-// The below combination of "indexes" and colors in the colorTable() LUT is to bypass the stale closure that the knob
-// would otherwise have.
+// The combination of "indexes" and colors in the colorTable() look-up table (LUT) is designed to circumvent
+// the issue of a stale closure that would occur with the knob otherwise.
 
-/// Index of the color options.
+/// The index of the color options.
 List<Option<int>> colorOptions = const [
   Option(label: "piccolo", value: 0),
   Option(label: "hit", value: 1),
@@ -50,7 +50,7 @@ List<Option<int>> colorOptions = const [
   Option(label: "transparent", value: 39),
 ];
 
-/// LUT for the color options.
+/// The look-up table for the color options.
 List<Color?> colorTable(BuildContext context) => [
       context.moonColors!.piccolo,
       context.moonColors!.hit,

example/lib/src/storybook/stories/accordion.dart

@@ -142,7 +142,7 @@ class _AccordionStoryState extends State<AccordionStory> {
 
     final showBorderKnob = context.knobs.boolean(
       label: "showBorder",
-      description: "Show border around MoonAccordion.",
+      description: "Show border for MoonAccordion.",
     );
 
     final showDividerKnob = context.knobs.boolean(
@@ -153,7 +153,7 @@ class _AccordionStoryState extends State<AccordionStory> {
 
     final showShadowKnob = context.knobs.boolean(
       label: "Show shadows",
-      description: "Show shadows under MoonAccordion.",
+      description: "Show shadows for MoonAccordion.",
       initial: true,
     );
 

example/lib/src/storybook/stories/alert.dart

@@ -116,7 +116,7 @@ class _AlertStoryState extends State<AlertStory> {
 
     final showDisabledKnob = context.knobs.boolean(
       label: "Disabled",
-      description: "onTrailingTap() is null.",
+      description: "MoonAlert onTrailingTap() is null.",
     );
 
     final BorderRadiusGeometry? borderRadius =

example/lib/src/storybook/stories/auth_code.dart

@@ -13,7 +13,7 @@ class AuthCodeStory extends StatelessWidget {
   Widget build(BuildContext context) {
     final mainAxisAlignmentKnob = context.knobs.nullable.options(
       label: "mainAxisAlignment",
-      description: "Horizontal alignment of MoonAuthCode input fields.",
+      description: "Horizontal alignment for MoonAuthCode input fields.",
       enabled: false,
       initial: MainAxisAlignment.center,
       options: const [
@@ -28,7 +28,7 @@ class AuthCodeStory extends StatelessWidget {
 
     final shapeKnob = context.knobs.nullable.options(
       label: "shape",
-      description: "Shape of the MoonAuthCode input fields.",
+      description: "Shape of MoonAuthCode input fields.",
       enabled: false,
       initial: AuthFieldShape.box,
       options: const [
@@ -62,7 +62,7 @@ class AuthCodeStory extends StatelessWidget {
 
     final selectedFillColorKnob = context.knobs.nullable.options(
       label: "selectedFillColor",
-      description: "MoonColors variants for selected MoonAuthCode input field.",
+      description: "MoonColors variants for MoonAuthCode selected input field.",
       enabled: false,
       initial: 0,
       // piccolo
@@ -73,7 +73,7 @@ class AuthCodeStory extends StatelessWidget {
 
     final activeFillColorKnob = context.knobs.nullable.options(
       label: "activeFillColor",
-      description: "MoonColors variants for active MoonAuthCode input fields.",
+      description: "MoonColors variants for MoonAuthCode active input field.",
       enabled: false,
       initial: 0,
       // piccolo
@@ -84,7 +84,7 @@ class AuthCodeStory extends StatelessWidget {
 
     final inactiveFillColorKnob = context.knobs.nullable.options(
       label: "inactiveFillColor",
-      description: "MoonColors variants for inactive MoonAuthCode input fields.",
+      description: "MoonColors variants for MoonAuthCode inactive input field.",
       enabled: false,
       initial: 0,
       // piccolo
@@ -95,7 +95,7 @@ class AuthCodeStory extends StatelessWidget {
 
     final selectedBorderColorKnob = context.knobs.nullable.options(
       label: "selectedBorderColor",
-      description: "MoonColors variants for selected MoonAuthCode input field border.",
+      description: "MoonColors variants for MoonAuthCode selected input field border.",
       enabled: false,
       initial: 0,
       // piccolo
@@ -106,7 +106,7 @@ class AuthCodeStory extends StatelessWidget {
 
     final activeBorderColorKnob = context.knobs.nullable.options(
       label: "activeBorderColor",
-      description: "MoonColors variants for active MoonAuthCode input fields borders.",
+      description: "MoonColors variants for MoonAuthCode active input field border.",
       enabled: false,
       initial: 0,
       // piccolo
@@ -117,7 +117,7 @@ class AuthCodeStory extends StatelessWidget {
 
     final inactiveBorderColorKnob = context.knobs.nullable.options(
       label: "inactiveBorderColor",
-      description: "MoonColors variants for inactive MoonAuthCode input fields borders.",
+      description: "MoonColors variants for MoonAuthCode inactive input field border.",
       enabled: false,
       initial: 0,
       // piccolo
@@ -242,7 +242,7 @@ class AuthCodeStory extends StatelessWidget {
                   final RegExp regex = RegExp(r'^\d+$');
 
                   return pin != null && pin.length == 4 && !regex.hasMatch(pin)
-                      ? 'The input must only contain numbers'
+                      ? 'The input must only contain numbers.'
                       : null;
                 },
                 errorBuilder: (BuildContext context, String? errorText) {

example/lib/src/storybook/stories/avatar.dart

@@ -113,7 +113,7 @@ class AvatarStory extends StatelessWidget {
         mainAxisAlignment: MainAxisAlignment.center,
         children: [
           const TextDivider(
-            text: "Customisable MoonAvatar",
+            text: "MoonAvatar",
             paddingTop: 0,
           ),
           MoonAvatar(
@@ -133,7 +133,7 @@ class AvatarStory extends StatelessWidget {
               ),
             ),
           ),
-          const TextDivider(text: "Preset MoonAvatar with image background"),
+          const TextDivider(text: "Customized MoonAvatar with image background"),
           MoonAvatar(
             avatarSize: avatarSizeKnob,
             badgeSize: badgeSizeKnob?.toDouble(),

example/lib/src/storybook/stories/bottom_sheet.dart

@@ -42,7 +42,7 @@ class BottomSheetStory extends StatelessWidget {
 
     final heightKnob = context.knobs.nullable.slider(
       label: "height",
-      description: "Height of the bottomsheet.",
+      description: "Height of MoonBottomSheet.",
       enabled: false,
       initial: 0.64,
       min: 0.1,

example/lib/src/storybook/stories/breadcrumb.dart

@@ -22,7 +22,7 @@ class _BreadcrumbStoryState extends State<BreadcrumbStory> {
   Widget build(BuildContext context) {
     final itemColorKnob = context.knobs.nullable.options(
       label: "Item color",
-      description: "MoonColors variants for the MoonBreadcrumb's item.",
+      description: "MoonColors variants for MoonBreadcrumb item.",
       enabled: false,
       initial: 0,
       // piccolo
@@ -33,7 +33,7 @@ class _BreadcrumbStoryState extends State<BreadcrumbStory> {
 
     final currentItemColorKnob = context.knobs.nullable.options(
       label: "Current item color",
-      description: "MoonColors variants for the current MoonBreadcrumb's item.",
+      description: "MoonColors variants for MoonBreadcrumb current item.",
       enabled: false,
       initial: 0,
       // piccolo
@@ -44,7 +44,7 @@ class _BreadcrumbStoryState extends State<BreadcrumbStory> {
 
     final hoverEffectColorKnob = context.knobs.nullable.options(
       label: "hoverEffectColor",
-      description: "MoonColors variants for the MoonBreadcrumb's item on hover.",
+      description: "MoonColors variants for MoonBreadcrumb item on hover.",
       enabled: false,
       initial: 0,
       // piccolo
@@ -55,7 +55,7 @@ class _BreadcrumbStoryState extends State<BreadcrumbStory> {
 
     final dividerColorKnob = context.knobs.nullable.options(
       label: "dividerColor",
-      description: "MoonColors variants for the MoonBreadcrumb's divider.",
+      description: "MoonColors variants for MoonBreadcrumb divider.",
       enabled: false,
       initial: 0,
       // piccolo
@@ -66,36 +66,36 @@ class _BreadcrumbStoryState extends State<BreadcrumbStory> {
 
     final itemCountKnob = context.knobs.nullable.sliderInt(
       label: "Item count",
-      description: "Total count of items for the MoonBreadcrumb.",
+      description: "Total count of items for MoonBreadcrumb.",
       enabled: false,
       initial: 7,
       max: 12,
     );
 
     final visibleItemCountKnob = context.knobs.nullable.sliderInt(
       label: "visibleItemCount",
-      description: "Count of items to display for the MoonBreadcrumb.",
+      description: "Number of items to display for MoonBreadcrumb.",
       enabled: false,
       initial: 3,
       max: 12,
     );
 
     final gapKnob = context.knobs.nullable.sliderInt(
       label: "gap",
-      description: "Gap between the MoonBreadcrumb's items.",
+      description: "Gap between MoonBreadcrumb items.",
       enabled: false,
       initial: 8,
       max: 16,
     );
 
     final showLeadingKnob = context.knobs.boolean(
       label: "leading",
-      description: "Show widget in the MoonBreadcrumb item's leading slot.",
+      description: "Show widget in MoonBreadcrumb item leading slot.",
     );
 
     final showTrailingKnob = context.knobs.boolean(
       label: "trailing",
-      description: "Show widget in the MoonBreadcrumb item's trailing slot.",
+      description: "Show widget in MoonBreadcrumb item trailing slot.",
     );
 
     return Column(
@@ -146,7 +146,7 @@ class _BreadcrumbStoryState extends State<BreadcrumbStory> {
             ),
           ],
         ),
-        const TextDivider(text: "Custom MoonBreadcrumb with MoonDropdown"),
+        const TextDivider(text: "Customized MoonBreadcrumb with MoonDropdown"),
         StatefulBuilder(
           builder: (context, setState) {
             return MoonBreadcrumb(

example/lib/src/storybook/stories/button.dart

@@ -111,7 +111,7 @@ class ButtonStory extends StatelessWidget {
 
     final isDisabledKnob = context.knobs.boolean(
       label: "Disabled",
-      description: "onTap() or onLongPress() is null.",
+      description: "MoonButton onTap() or onLongPress() is null.",
     );
 
     IconData resolveIconVariant(MoonButtonSize? buttonSize) {
@@ -142,7 +142,7 @@ class ButtonStory extends StatelessWidget {
         child: Column(
           children: [
             const TextDivider(
-              text: "Base and MoonIcon MoonButton",
+              text: "Base and icon MoonButton",
               paddingTop: 0,
             ),
             MoonButton(
@@ -204,7 +204,7 @@ class ButtonStory extends StatelessWidget {
               label: showLabelKnob ? const Text("MoonTextButton") : null,
               trailing: showTrailingKnob ? Icon(resolvedIconVariant) : null,
             ),
-            const TextDivider(text: "Custom MoonButtons with non-standard children"),
+            const TextDivider(text: "Customized MoonButtons with non-standard children"),
             MoonButton(
               onTap: isDisabledKnob ? null : () {},
               height: 40,