Clean up event system API documentation

[SeanCurtis-TRI]

The new API for the event system is far-reaching and complex. The decision was made to allow it through without having wholly satisfying documentation because of its complexity. Accordingly, this issue is intended to track the known documentation issues (which may or may not be specifically called out in todos in the code):

Doxygen needs:

• [ ] Overall event system module documentation. Provide a single doxygen page which explains:
  • Base vocabulary for discussing events in Drake (e.g., register/schedule/generate, dispatch, trigger, handle, process...what do these words mean? In event.h, we indicate that an event is "triggered" by calling the API for "handling"...that's just confusing).
  • Reivisit "force" trigger type. See discussion here
  • Guide to authors of a new LeafSystems, what type of events they would register,
  • Guidance on when a DoPublish method might be overloaded.
• [ ] in event.h document the various trigger types to match kPerStep in detail.
• [ ] Document the use-case/value of having an event without an event handler (see event.h), example
• [ ] Concrete event types class documentation has the language "custom handling". The documentation of Event refers to a no-op handling. This is confusing because the architecture allows handling either in the event callback or in the DoPublish (or corresponding method) as handling as well.
• [ ] event_collection.h
  • document strange ownership architecture in collections.
  • LeafEventCollection::MakeForcedEventCollection() - the role this method plays in the ecosystem needs to be clear.
  • CompositeEventCollection::add_publish_event() - clarify the relationship between the base class and the type of EventCollection it contains.
• [ ] system.h
  • Make sure Publish, CalcDiscreteUpdate, and CalcUnrestrictedUpdate (and corresponding methods, discuss event processing in terms of a common vernacular (defined in the module).
  • Clean up ambiguous language on Publish (https://reviewable.io/reviews/robotlocomotion/drake/6050#-Kmm-wpyNB4x_qF8Sb_R:-Kn_czQo0sWqn-g3ojiY:b-n5fyb3) and comment on line 196.
  • Clean up language about "dispatching handlers". See documentation on DispatchPublishHandler().

Implementation details for developers:

• [ ] Diagram.h
  • [ ] AllocateForced_____EventCollection(). Document how this non-obvious C++ machinery works.
  • [ ] GetSubSystemStuff(). Probably need to revisit the name of this method.
• [ ] diagram_test.cc - Tests like UpdateDiscreteVariables rely on CalcNextUpdate to clear the event collection.

[edrumwri]

Just a couple of comments on the issue since it's finally receiving attention. One note is that Reviewable is failing to preserve context with the review comments (the comments are intact but the places pointed to in the code are not.)

Doxygen needs:

  * Guide to authors of a new `LeafSystem`s, what type of events they would register,

I agree completely and started to add this to LeafSystem. Unfortunately, there is now zero information for LeafSystem authors so adding info about events there would now be incongruous. Issue #8616 already covers that issue (I've updated it to point this out). I also put a little info into my upcoming PR (#12501) for addressing this present issue.

  * [ ]  `GetSubSystemStuff()`. Probably need to revisit the _name_ of this method.

It's used for lots of, ahem, stuff, so I think this uninformative name is actually appropriate.