apply changes from code review

layouts/partials/events/example.html

@@ -3,7 +3,7 @@
   Renders an event example.  Resolves `$ref`s, serializes as JSON, and ensures
   that it can be included in HTML.
 
-  This partial is called with the example data as its context.
+  This partial is called with the example event object as its context.
 
 */}}
 

layouts/partials/events/render-event.html

@@ -8,7 +8,7 @@
     If `desired_example_name` is omitted we render all examples
     whose names start with the `event_name`.
     * `title` (optional): the title to display.  May contain markdown.  Defaults to
-    `event_name` wrapped in a <code> element
+    `event_name` wrapped in a <code> element.
 
 */}}
 

layouts/shortcodes/event.html

@@ -2,11 +2,24 @@
 
   This template is used to render an event.
 
-  It expects to be passed an `event` parameter, which is the name of a schema file under
+  It takes the following parameters:
-  "data/event-schemas/schema". The file extension is omitted. For example:
+
+    * `event` (required): the name of a schema file under "data/event-schemas/schema".
+      The file extension is omitted. For example:
 
         {{% event event="m.accepted_terms" %}}
 
+    * `desired_example_name` (optional): the name of the example file to use under
+      "data/event-schemas/examples", without the file extension.  If omitted
+      defaults to the example file with the same name as the `event` parameter, and
+      (if the name does not contain a "$"), all examples that begin with the name
+      given by the `event` parameter followed by a "$".  For example, if the
+      `event` parameter is "m.foo", then by default it will include the "m.foo"
+      example along with any examples starting with "m.foo$".
+
+    * `title` (optional): the title to use for the event.  Defaults to the name
+      given in the `event` parameter.
+
   This template replaces the old {{*_event}} template.
 
 */}}