diff --git a/layouts/partials/events/example.html b/layouts/partials/events/example.html
index 7059d453..181de88f 100644
--- a/layouts/partials/events/example.html
+++ b/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.
 
 */}}
 
diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html
index 71951937..369a80db 100644
--- a/layouts/partials/events/render-event.html
+++ b/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.
 
 */}}
 
diff --git a/layouts/shortcodes/event.html b/layouts/shortcodes/event.html
index 4ae7c37f..a9838542 100644
--- a/layouts/shortcodes/event.html
+++ b/layouts/shortcodes/event.html
@@ -2,10 +2,23 @@
 
   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
-  "data/event-schemas/schema". The file extension is omitted. For example:
+  It takes the following parameters:
 
-      {{% event event="m.accepted_terms" %}}
+    * `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.