Fix MKWS-227.

Finish the events section.
And therefore finish the developer documentation.
And therefore finish ALL the documentation.

diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown
index 36a7e2f..3832c54 100644 (file)
--- a/doc/mkws-developer.markdown
+++ b/doc/mkws-developer.markdown
@@ -344,31 +344,72 @@ Events
 
 The following events are generated by the widget-set code:
 
-* `authenticated` (authName, realm)
-
-* `ready`
-
-* `log` (m_teamName, timestamp, s)
-
-* `targets` (data)
-
-* `stat` (data)
-
-* `firstrecords` (hitcount)
-
-* `complete` (hitcount)
-
-* `facets` (data)
-
-* `pager` (data)
-
-* `records` (data)
-
-* `record` (data)
-
-* `navi` -- consult `team.filters`.
-
-
+* `authenticated` (authName, realm) --
+       When authentication is completed successfully, this event is
+       published to _all_ teams. Two parameters are passed: the
+       human-readable name of the library that has been authenticated
+       onto, and the correponding machine-readable library ID.
+
+* `ready` --
+       Published to _all_ teams when they are ready to search. No
+       parameters are passed. This event is used to implement
+       automatic searching, and should probably not be used by
+       application code.
+
+* `stat` (data) --
+       Published to a team when a `stat` response is reveived from
+       Pazpar2. The data from the response is passed as a parameter.
+
+* `firstrecords` (hitcount) --
+       Published to a team when the first set of records is found by
+       a search. The number of records found (so far) is passed as
+       the parameter.
+
+* `complete` (hitcount) --
+       Published to a team when a search is complete, and no more
+       records will be found (i.e. all targets have either responded
+       or failed with an error). The final number of records found is
+       passed as the parameter.
+
+* `targets` (data) --
+       Published to a team when a `bytarget` response is reveived from
+       Pazpar2. The data from the response is passed as a parameter.
+
+* `facets` (data) --
+       Published to a team when a `term` response is reveived from
+       Pazpar2. The data from the response is passed as a parameter.
+
+* `pager` (data) --
+       Published to a team when a `show` response is reveived from
+       Pazpar2. The data from the response is passed as a
+       parameter. This event is used to update the pager, showing how
+       many records have been found, which page is being displayed,
+       etc.
+
+* `records` (data) --
+       Also published to a team when a `show` response is reveived
+       from Pazpar2. The data from the response is passed as a
+       parameter. This event is used to update the displayed records.
+
+* `record` (data) --
+       Published to a team when a `record` response is reveived from
+       Pazpar2 (i.e. the full data for a single record). The data
+       from the response is passed as a parameter.
+
+* `navi` --
+       Published to a team when a new search is about to be
+       submitted. This is a signal that the navigation area, showing
+       which filters are in effect, should be updated. No parameter
+       is passed: the event handler should consult `team.filters` to
+       see what the prevailing set is.
+
+* `log` (teamName, timestamp, message) --
+       Published to a team when a message is about to be logged to
+       the console for debugging. Three arguments are passed: the
+       name of the team that generated the log message, a timestamp
+       string, and the message itself. Note that this event is _not_
+       published when the widget-set core code generates a log
+       message -- only when a team or a widget does.
 
 - - -