[Multiple components] Audit recent docs changes, part 1

Closes #10132 PiperOrigin-RevId: 345256835
material-components · Dec 2, 2020 · 8d8763e · 8d8763e
1 parent 62863b2
commit 8d8763e
Show file tree

Hide file tree

Showing 18 changed files with 373 additions and 367 deletions.
diff --git a/components/AppBar/README.md b/components/AppBar/README.md
diff --git a/components/AppBar/docs/assets/appbar-hero.png b/components/AppBar/docs/assets/appbar-hero.png
diff --git a/components/AppBar/docs/assets/appbar-types.png b/components/AppBar/docs/assets/appbar-types.png
diff --git a/components/AppBar/docs/assets/top-app-bar.gif b/components/AppBar/docs/assets/top-app-bar.gif
diff --git a/components/Buttons/README.md b/components/Buttons/README.md
@@ -7,6 +7,6 @@ The `MDCButton` class implements the following design components:
     * [Outlined button](docs/buttons.md/#outlined-button)
     * [Contained button](docs/buttons.md/#contained-button)
 * [Floating action buttons](docs/fabs.md)
-    * [Regular FABs](docs/fabs.md/#regular-fabs)
-    * [Mini FABs](docs/fabs.md/#mini-fabs)
-    * [Extended FABs](docs/fabs.md/#extended-fabs)
+    * [Regular FAB](docs/fabs.md/#regular-fab)
+    * [Mini FAB](docs/fabs.md/#mini-fab)
+    * [Extended FAB](docs/fabs.md/#extended-fab)
diff --git a/components/Buttons/docs/assets/buttons_hero.png b/components/Buttons/docs/assets/buttons_hero.png
diff --git a/components/Buttons/docs/assets/fab-hero.png b/components/Buttons/docs/assets/fab-hero.png
diff --git a/components/Buttons/docs/assets/fab-types.png b/components/Buttons/docs/assets/fab-types.png
diff --git a/components/Buttons/docs/buttons.md b/components/Buttons/docs/buttons.md
@@ -12,43 +12,40 @@ api_doc_root: true
 
 [Buttons](https://material.io/components/buttons/) allow users to take actions, and make choices, with a single tap.
 
-There are four types of buttons:
-
-1. [Text button](#text-button)
-2. [Outlined button](#outlined-button)
-3. [Contained button](#contained-button)
-4. [Toggle button](#toggle-button) (*not supported in iOS*)
+!["Button on a screen"](assets/buttons_hero.png)
 
-![Example of the four button types](assets/buttons_types.png)
+## Contents
 
+*   [Using buttons](#using-buttons)
+*   [Text button](#text-button)
+*   [Outlined button](#outlined-button)
+*   [Contained button](#contained-button)
+*   [Toggle button](#toggle-button)
+*   [Theming](#theming)
 
 ## Using buttons
 
-All Material buttons are implemented by `MDCButton`, a subclass of [UIButton](https://developer.apple.com/documentation/uikit/uibutton).
-* [GitHub source](https://github.com/material-components/material-components-ios/blob/develop/components/Buttons/src/MDCButton.h)
-
-### Install `MDCButton`
+### Installing
 
-`MDCButton` is used to implement all four Material Buttons. In order to use `MCDButton`, first add Buttons to your `Podfile`:
+In order to use Material buttons, first add the `Buttons` subspec to your `Podfile`:
 
 ```bash
 pod MaterialComponents/Buttons
 ```
 <!--{: .code-renderer.code-renderer--install }-->
 
-Then, run the installer.
+Then, run the installer:
 
 ```bash
 pod install
 ```
 
-After that, import the Buttons and initialize them using `alloc`/`init`.
+After that, import the relevant target or file and initialize your button.
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Swift
 ```swift
 import MaterialComponents.MaterialButtons
-import MaterialComponents.MaterialButtons_Theming
 
 let button = MDCButton()
 ```
@@ -57,13 +54,11 @@ let button = MDCButton()
 
 ```objc
 #import "MaterialButtons.h"
-#import <MaterialComponents/MaterialButtons+Theming.h>
 
 MDCButton *button = [[MDCButton alloc] init];
 ```
 <!--</div>-->
 
-
 ### Making Buttons accessible
 
 To help ensure your buttons are accessible to as many users as possible, please
@@ -129,7 +124,7 @@ button.hitAreaInsets = UIEdgeInsetsMake(verticalInset, horizontalInset, vertical
 
 #### Set the minimum visual size of the button
 
-Set your buttons to have a minimum size. [Material Buttons
+Set your buttons to have a minimum size. Though there are some exceptions, [Material Buttons
 guidelines](https://material.io/design/components/buttons.html#specs)
 typically recommend [a minimum height of 36 points and a minimum width of 64
 points](https://material.io/design/components/buttons.html#specs).
@@ -146,13 +141,6 @@ button.minimumSize = CGSizeMake(64, 36);
 ```
 <!--</div>-->
 
-#### Exceptions
-
-However there are
-[some](https://material.io/design/components/buttons.html#toggle-button) clear
-[exceptions](https://material.io/design/components/app-bars-bottom.html#specs)
-for these rules. Please adjust your buttons sizes accordingly.
-
 #### Using `accessibilityHint`
 
 Apple rarely recommends using the `accessibilityHint` because the label should
@@ -171,6 +159,19 @@ repeats weekly on the following day(s)." The list items do not need
 (representing a day of the week) has the `accessibilityHint` value, "Toggles
 this day."
 
+## Types
+
+There are four types of buttons:
+
+1. [Text button](#text-button)
+2. [Outlined button](#outlined-button)
+3. [Contained button](#contained-button)
+4. [Toggle button](#toggle-button) (*not supported in iOS*)
+
+![Example of the four button types](assets/buttons_types.png)
+
+All Material buttons are implemented by `MDCButton`, a subclass of [`UIButton`](https://developer.apple.com/documentation/uikit/uibutton).
+* [GitHub source](https://github.com/material-components/material-components-ios/blob/develop/components/Buttons/src/MDCButton.h)
 
 ## Text button
 
@@ -180,7 +181,7 @@ this day."
 
 ### Text button example
 
-To use a text button use the text button theming method on the MDCButton theming extension. For more information on theming extensions see the [Theming section](#theming-buttons). 
+To use a text button use the text button theming method on the `MDCButton` theming extension. For more information on theming extensions see the [Theming section](#theming). 
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Objective-C
@@ -237,7 +238,7 @@ A text button has a text label, a transparent container and an optional icon.
 
 ### Outlined button example
 
-To achieve an outlined button use the outlined button theming method on the MDCButton theming extension. To access the theming extension see the [Theming section](#theming-buttons). 
+To achieve an outlined button use the outlined button theming method on the `MDCButton` theming extension. To access the theming extension see the [Theming section](#theming). 
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Objective-C
@@ -294,7 +295,7 @@ An outlined button has a text label, a container, and an optional icon.
 
 ### Contained button example
 
-Contained buttons are implemented by [MDCButton](https://github.com/material-components/material-components-ios/blob/stable/components/Buttons/src/MDCButton.h). To achieve a contained button use the contained button theming method on the MDCButton theming extension. To access the theming extension see the [Theming section](#theming). 
+Contained buttons are implemented by `MDCButton`. To achieve a contained button use the contained button theming method on the `MDCButton` theming extension. To access the theming extension see the [Theming section](#theming).
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Objective-C
@@ -347,24 +348,24 @@ A contained button has a text label, a container, and an optional icon.
 
 [Toggle buttons](https://material.io/components/buttons/#toggle-button) can be used to select from a group of choices. They are not supported on iOS.
 
-## Theming buttons
+## Theming
 
-You can theme an MDCButton to match any of the Material Button styles using theming
+You can theme an `MDCButton` to match any of the Material Button styles using theming
 extensions. [Learn more about theming extensions](../../../docs/theming.md). Below is a screenshot of Material Buttons with the Material Design Shrine theme:
 
 ![Shrine buttons](assets/shrine-buttons.png)
 
 ### Buttons theming example
 
-To make use of the theming methods shown in the examples above install the Buttons theming extensions with Cocoapods. First, add the following line to your `Podfile`.
+To make use of the theming methods shown in the examples above install the Buttons theming extensions with Cocoapods. First, add the following line to your `Podfile`:
 
 ```bash
 pod MaterialComponents/Buttons+Theming
 ```
 
 <!--{: .code-renderer.code-renderer--install }-->
 
-Then Run the installer.
+Then Run the installer:
 
 ```bash
 pod install

diff --git a/components/Buttons/docs/fabs.md b/components/Buttons/docs/fabs.md
@@ -12,57 +12,48 @@ api_doc_root: true
 
 A floating action button (FAB) represents the primary action of a screen.
 
-There are three types of FABs:
+!["A FAB on a screen"](assets/fab-hero.png)
 
-1. [Regular FABs](#regular-fabs)
-2. [Mini FABs](#mini-fabs)
-3. [Extended FABs](#extended-fabs)
+## Contents
 
-<!--Get an image of a floating action button-->
+*   [Using FABs](#using-fabs)
+*   [Regular FAB](#regular-fab)
+*   [Mini FAB](#mini-fab)
+*   [Extended FAB](#extended-fab)
+*   [Theming](#theming)
 
 ## Using FABs
 
-A FAB performs the primary, or most common, action on a screen. It appears in front of all screen content, typically as a circular shape with an icon in its center. 
-
-FABs are implemented by `MDCFloatingButton`, a subclass of [MDCButton](https://github.com/material-components/material-components-ios/blob/stable/components/Buttons/src/MDCButton.h).
-* [GitHub source](https://github.com/material-components/material-components-ios/blob/develop/components/Buttons/src/MDCFloatingButton.h)
-
-Only use a FAB if it is the most suitable way to present a screen’s primary action.
-
-FABs should be provided with a templated image for their normal state and then themed accordingly.
-
-### Installing FABs
+### Installing
 
-Because MDCFloatingButton is a subclass of [MDCButton](buttons.md), the steps for installing it are the same.
+Because `MDCFloatingButton` is a subclass of [MDCButton](buttons.md), the steps for installing it are the same.
 
-In order to use `MDCFloatingButton`, first add Buttons to your `Podfile`.
+In order to use `MDCFloatingButton`, first add the `Buttons` subspec to your `Podfile`:
 
 ```bash
 pod MaterialComponents/Buttons
 ```
 <!--{: .code-renderer.code-renderer--install }-->
 
-Then, run the installer.
+Then, run the installer:
 
 ```bash
 pod install
 ```
 
-After that, import the Buttons and initialize an MDCFloatingButton using `alloc`/`init`.
+After that, import the relevant target or file and initialize an `MDCFloatingButton`.
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Swift
 ```swift
 import MaterialComponents.MaterialButtons
-import MaterialComponents.MaterialButtons_Theming
 
 let fab = MDCFloatingButton()
 ```
 
 #### Objective-C
 ```objc
 #import "MaterialButtons.h"
-#import <MaterialComponents/MaterialButtons+Theming.h>
 
 MDCFloatingButton *fab = [[MDCFloatingButton alloc] init];
 ```
@@ -101,7 +92,6 @@ floatingButton.minimumSize = CGSizeMake(64, 36);
 ```
 <!--</div>-->
 
-
 * Set the [touch areas to at least 44 points high and 44
 wide](https://material.io/design/layout/spacing-methods.html#touch-click-targets).
     To minimize FAB's visual size while allowing for larger [touchable areas](https://material.io/design/layout/spacing-methods.html#touch-click-targets), set the `hitAreaInsets` to a negative value. Maintain sufficient distance between the FAB touch targets. For more see the [Touch and click
@@ -148,13 +138,26 @@ repeats weekly on the following day(s)." The list items do not need
 (representing a day of the week) has the `accessibilityHint` value, "Toggles
 this day."
 
-## Regular FABs
+## Types
+
+There are three types of FABs:
+
+1. [Regular FABs](#regular-fabs)
+2. [Mini FABs](#mini-fabs)
+3. [Extended FABs](#extended-fabs)
+
+![Three FABs, one of each type.](assets/fab-types.png)
+
+All three types of FABs are implemented by `MDCFloatingButton`, a subclass of [MDCButton](https://github.com/material-components/material-components-ios/blob/stable/components/Buttons/src/MDCButton.h).
+* [GitHub source](https://github.com/material-components/material-components-ios/blob/develop/components/Buttons/src/MDCFloatingButton.h)
+
+## Regular FAB
 
 ![Regular FAB example](assets/regular-fab.png)
 
 Regular FABs are FABs that are not expanded and are a regular size.
 
-### Regular FABs example
+### Regular FAB example
 
 To create a regular FAB use the `+floatingButtonWithShape:` constructor with a value of `MDCFloatingButtonShapeDefault` and make sure the `mode` property is set to `MDCFloatingButtonModeNormal`.
 
@@ -198,15 +201,15 @@ A regular FAB has a container and an icon.
 **Icon**                                        | `imageView`        | `setImage:forState:`<br/>`imageForState:` | `nil`
 **Color**                                       | `imageView.tintColor` | `setImageViewTintColor:forState:`<br/>`imageViewTintColorForState:` | `nil`
 
-## Mini FABs
+## Mini FAB
 
 ![Mini FAB example](assets/mini-fab.png)
 
 A mini FAB should be used on smaller screens.
 
 Mini FABs can also be used to create visual continuity with other screen elements.
 
-### Mini FABs example
+### Mini FAB example
 
 To create a mini FAB use the `+floatingButtonWithShape:` constructor with a value of `MDCFloatingButtonShapeMini` and make sure the `mode` property is set to `MDCFloatingButtonModeNormal`.
 
@@ -250,13 +253,13 @@ A mini FAB has a container and an icon.
 **Icon**                                        | `imageView`        | `setImage:forState:`<br/>`imageForState:` | `nil`
 **Color**                                       | `imageView.tintColor` | `setImageViewTintColor:forState:`<br/>`imageViewTintColorForState:` | `nil`
 
-## Extended FABs
+## Extended FAB
 
 ![Extended FAB example](assets/extended-fab.png)
 
 The extended FAB is wider, and it includes a text label.
 
-### Extended FABs example
+### Extended FAB example
 
 
 To create an extended FAB use the `+floatingButtonWithShape:` constructor with a value of `MDCFloatingButtonShapeDefault` and make sure the `mode` property is set to `MDCFloatingButtonModeExpanded`.
@@ -314,22 +317,20 @@ An extended FAB has a text label, a transparent container and an optional icon.
 
 ## Theming
 
-You can theme an MDCFloatingButton to have a secondary theme using the MDCFloatingButton theming
+You can theme an `MDCFloatingButton` to have a secondary theme using the `MDCFloatingButton` theming
 extension. [Learn more about theming extensions and container schemes](../../../docs/theming.md). Below is a screenshot of Material FABs with the Material Design Shrine theme:
 
 ![Shrine FABs](assets/shrine-fabs.png)
 
-### FAB theming example
-
-To make use of the theming methods shown in the examples above install the Buttons theming extensions with Cocoapods. First, add the following line to your `Podfile`.
+To make use of the theming methods shown in the examples above install the Buttons theming extensions with Cocoapods. First, add the following line to your `Podfile`:
 
 ```bash
 pod MaterialComponents/Buttons+Theming
 ```
 
 <!--{: .code-renderer.code-renderer--install }-->
 
-Then Run the installer.
+Then Run the installer:
 
 ```bash
 pod install
@@ -351,7 +352,7 @@ import MaterialComponents.MaterialButtons_Theming
 ```
 <!--</div>-->
 
-From there, pass a container scheme into the following theming method on an MDCFloatingButton instance.
+From there, pass a container scheme into the theming method on an `MDCFloatingButton` instance.
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Swift