More documentation for drawers. (#6697)

Closes https://github.com/flutter/flutter/issues/5781

packages/flutter/lib/src/material/drawer.dart

@@ -34,11 +34,19 @@ const Duration _kBaseSettleDuration = const Duration(milliseconds: 246);
 /// Typically, the child of the drawer is a [Block] whose first child is a
 /// [DrawerHeader] that displays status information about the current user.
 ///
+/// The [Scaffold] automatically shows an appropriate [IconButton], and handles
+/// the edge-swipe gesture, to show the drawer.
+///
 /// See also:
 ///
-///  * [Scaffold.drawer]
-///  * [DrawerItem]
-///  * [DrawerHeader]
+///  * [Scaffold.drawer], where one specifies a [Drawer] so that it can be
+///    shown.
+///  * [Scaffold.of], to obtain the current [ScaffoldState], which manages the
+///    display and animation of the drawer.
+///  * [ScaffoldState.openDrawer], which displays its [Drawer], if any.
+///  * [Navigator.pop], which closes the drawer if it is open.
+///  * [DrawerItem], a widget for items in drawers.
+///  * [DrawerHeader], a widget for the top part of a drawer.
 ///  * <https://material.google.com/patterns/navigation-drawer.html>
 class Drawer extends StatelessWidget {
   /// Creates a material design drawer.

packages/flutter/lib/src/material/drawer_item.dart

@@ -52,6 +52,8 @@ class DrawerItem extends StatelessWidget {
   /// Called when the user taps this drawer item.
   ///
   /// If null, the drawer item is displayed as disabled.
+  ///
+  /// To close the [Drawer] when an item is pressed, call [Navigator.pop].
   final VoidCallback onPressed;
 
   /// Whether this drawer item is currently selected.

packages/flutter/lib/src/material/scaffold.dart

@@ -504,6 +504,12 @@ class ScaffoldState extends State<Scaffold> with TickerProviderStateMixin {
   ///
   /// If the scaffold has a non-null [Scaffold.drawer], this function will cause
   /// the drawer to begin its entrance animation.
+  ///
+  /// Normally this is not needed since the [Scaffold] automatically shows an
+  /// appropriate [IconButton], and handles the edge-swipe gesture, to show the
+  /// drawer.
+  ///
+  /// To close the drawer once it is open, use [Navigator.pop].
   void openDrawer() {
     _drawerKey.currentState?.open();
   }