update docs markdown

Author: mmalerba

src/material/card/card.md

@@ -2,38 +2,55 @@
 
 <!-- example(card-overview) -->
 
-
 ### Basic card sections
-The most basic card needs only an `<mat-card>` element with some content. However, Angular Material
-provides a number of preset sections that you can use inside of an `<mat-card>`:
 
+The most basic card needs only an `<mat-card>` element with some content. However, Angular Material
+provides a number of preset sections that you can use inside a `<mat-card>`:
 
-| Element                | Description                                            |
-| ---------------------- | ------------------------------------------------------ |
-| `<mat-card-title>`     | Card title                                             |
-| `<mat-card-subtitle>`  | Card subtitle                                          |
-| `<mat-card-content>`   | Primary card content. Intended for blocks of text      |
-| `<img mat-card-image>` | Card image. Stretches the image to the container width |
-| `<mat-card-actions>`   | Container for buttons at the bottom of the card        |
-| `<mat-card-footer>`    | Section anchored to the bottom of the card             |
+| Element                  | Description                                                    |
+|--------------------------|----------------------------------------------------------------|
+| `<mat-card-header>`      | Section anchored to the top of the card (adds padding)         |
+| `<mat-card-content>`     | Primary card content (adds padding)                            |
+| `<img mat-card-image>`   | Card image. Stretches the image to the container width         |
+| `<mat-card-actions>`     | Container for buttons at the bottom of the card (adds padding) |
+| `<mat-card-footer>`      | Section anchored to the bottom of the card                     |
 
 These elements primary serve as pre-styled content containers without any additional APIs. 
 However, the `align` property on `<mat-card-actions>` can be used to position the actions at the 
-`'start'` or `'end'` of the container.  
+`'start'` or `'end'` of the container.
+
+### Card padding
 
+The `<mat-card>` element itself does not add any padding around its content. This allows developers
+to customize the padding to their liking by applying padding to the elements they put in the card.
+
+In many cases developers may just want the standard padding specified in the Material Design spec.
+In this case, the `<mat-card-header>`, `<mat-card-content>`, and `<mat-card-footer>` sections can be
+used.
+
+* `<mat-card-content>` adds standard padding along its sides, as well as along the top if it is the
+  first element in the `<mat-card>`, and along the bottom if it is the last element in the
+  `<mat-card>`.
+* `<mat-card-header>` adds standard padding along its sides and top.
+* `<mat-card-actions>` adds padding appropriate for the action buttons at the bottom of a card. 
 
 ### Card headers
-In addition to the aforementioned sections, `<mat-card-header>` gives the ability to add a rich
-header to a card. This header can contain:
 
-| Element                 | Description                                  |
-| ----------------------- | -------------------------------------------- |
-| `<mat-card-title>`      | A title within the header                    |
-| `<mat-card-subtitle>`   | A subtitle within the header                 |
-| `<img mat-card-avatar>` | An image used as an avatar within the header |
+A `<mat-card-header>` can contain any content, but there are several predefined elements
+that can be used to create a rich header to a card. These include:
 
+| Element                  | Description                                          |
+|--------------------------|------------------------------------------------------|
+| `<mat-card-title>`       | A title within the header                            |
+| `<mat-card-subtitle>`    | A subtitle within the header                         |
+| `<img mat-card-avatar>`  | An image used as an avatar within the header         |
+
+In addition to using `<mat-card-title>` and `<mat-card-subtitle>` directly within the
+`<mat-card-header>`, they can be further nested inside a `<mat-card-title-group>` in order arrange
+them with a (non-avatar) image.
 
 ### Title groups
+
 `<mat-card-title-group>` can be used to combine a title, subtitle, and image into a single section.
 This element can contain:
 * `<mat-card-title>`