add list of preconditions to event docstrings

[sed-i]

It would be valuable to document what each event guarantees.
For example, "RelationJoinedEvent" guarantees (i.e. has a precondition) that peer buckets are visible (cf. #542).

operator/ops/charm.py

Lines 352 to 362 in 37e3399

	class RelationJoinedEvent(RelationEvent):
	"""Event triggered when a new unit joins a relation.
	This event is triggered whenever a new unit of a related
	application joins the relation. The event fires only when that
	remote unit is first observed by the unit. Callback methods bound
	to this event may set any local unit settings that can be
	determined using no more than the name of the joining unit and the
	remote ``private-address`` setting, which is always available when
	the relation is created and is by convention not deleted.
	"""

[balbirthomas]

It would be valuable to document what each event guarantees.
For example, "RelationJoinedEvent" guarantees (i.e. has a precondition) that peer buckets are visible (cf. #542).

I wonder if this should be in the docstring of get_binding() also. The precondition of get_binding() network for a peer relation or any relation is that the relation joined event for that particular relation and unit has happened. It may be fair to add a cross reference in RelationJoinedEvent saying once this event has occured get_binding() will return a valid address.

[sed-i]

Enumerating entry pathways is also useful, for example:

• RelationJoined:
  1. as part of the startup sequence (may appear multiple times);
  2. re-entry after defer().
• RelationChanged:
  1. immediately after a newly joint unit receives RelationJoined, all of its peers receive RelationChanged.
  2. when relation data bucket is modified.
  3. re-entry after defer().
• PebbleReady:
  1. as part of the startup sequence (only once);
  2. re-entry after defer().

[benhoyt]

I think we can probably improve our docs here in places, however, I think it's probably better that the details are described in the Juju docs rather than in the ops API docs. We could even shorten our ops docs in some cases, and perhaps link to the relevant Juju doc.

[benhoyt]

@tmihoc You had some thoughts about making Juju event docs clearer -- what was your concrete plan for that again?