improve doc-strings and definitions of modes and mode maps

* Explicitly define all Magit mode keymaps, even when those that do not
  have any special bindings by default (`magit-stash-mode-map',
  `magit-reflog-mode-map', `magit-diff-mode-map').

* Set the parent keymap explicitly in each mode keymap definition,
  instead of relying on `define-derived-mode' doing it for as (at a less
  than perfect time).

* Add doc-string to all mode keymaps.  Except for `magit-mode-map' use
  what would have been generated by `define-derived-mode'.

* For all modes, add a link to the parent of the modes keymap in the
  mode function doc-string.  Wrap it in a sentence similar to that about
  the parent mode and its which is automatically appended.

* Beyond the above also give the mode doc-strings a uniform form by.
  That form isn't perfect but at least we now have a reasonable summary
  in all mode doc-strings.

* Change the doc-string summary of `magit-mode' to explain that it is
  the parent mode of other Magit modes (which also implies it isn't
  intended for direct use, like `special-mode').
use define-derived-mode to define magit-mode
create "Stash Mode" section

Previously everything related to stashes was defined in
"Acting"/"Stashing".  Everything related to a "command"/"topic"
is not actually a bad idea, but it is not how it is done for
anything else in Magit.  So let us not do it here either.
give mode section a common order

Use the same definition order for all sections in `magit.el' that
contain the definition of a Magit major mode, its refresh function, and
the related entry command(s); and then possibly other things.

  This is something I wanted to do for a long time.  I didn't do so
  because it makes inspecting history more difficult.  But considering
  how much grief the disorder has caused me, messing with the history is
  the lesser evil.

  Also note that I am not switching from one common order to another.
  It appears that there was a common order at some point (which is about
  the opposite of what I am now doing).  But over time that order was
  lost because inconsistent additions were made to the various mode
  sections, effectively destroying the similarity and in some cases also
  making the section very disorganized even when looked at in isolation.

The new prototypical order is this:

1. `magit-*-mode'
2. `magit-*-buffer-name'
3. `magit-INVOCE-*' -- Creates a buffer named (2), puts it in (1) mode
   and refreshes with (4).
4. `magit-refresh-*-buffer'

See the "Diff Mode" section for the prototypical example.

  This does not only benefit my own ocd.  The new order also makes it
  easier for readers new to the source.  The doc-string of the mode
  servers as a short summary.  The "invocation" commands come next,
  because the have (should have) a useful doc-string, are usually short,
  and the "refresher" that follows is often long and not of interest to
  the casual reader.

The lack of a common order didn't just make it harder to read the mode
sections it also lead to inconsistencies.  Some of these could have
prevented with a common order, others probably not.

Also not all of the remaining inconsistencies are actually bad.  Some
are just due to differences in the complexity of these modes.

The implementation of support functionality like washing differ in
complexity between modes and/or are shared between modes.  Depending on
this some of implementation details might be defined in independent
and/or shared sections elsewhere in the file.  In some cases this should
be corrected but that's a different issue.

What is important is that at least the parts that exist for each mode
share the same definition, so that the remaining differences do not
cause to much confusion.

Some mode sections also lexically contain:

0. Additional variables that have to be defined early.
   Many of these variables should be abstracted away.
5. Section inserters used in (4).
6. Washers used in (5).
7. Wacky stuff that needs to be cleaned and generalized because
   it can also be used elsewhere.

Some mode section are now split (or were already split) into
preliminary/temporary sub-sections.  These subsection will likely
disappear after some cleanup.  If they do not they will get better
headings.  I also added some TODO markers which should also be gone
soon.
add missing magit-{*}-buffer-name variables, change doc-strings

Add the missing `magit-{*}-buffer-name' variables so that such a
variable exists for each Magit mode.  Two such variables have to
be declared to suppress compile warnings, so be it.

Also add doc-strings to existing variables that lack it and give
all such doc-strings the same form.

Also rename `magit{--cherry => -cherry}-buffer-name'.
Merge branch 'modes'

Conflicts:
	magit-flow.el