Update documentation_style.rst

7 years ago · 196e668768
parent 726af76a77
commit 196e668768
1 changed files with 6 additions and 1 deletions
--- a/meta/documentation_style.rst
+++ b/meta/documentation_style.rst
@ -77,7 +77,12 @@ When writing OpenAPI specifications for the API endpoints, follow these rules:
  end with a full stop. Examples: "Sends an event."; "Searches the directory."

 * ``description``: a longer description of the behaviour of this API, written
-  in complete sentences.
+  in complete sentences. Use multiple paragraphs if necessary.
+  
+  Example: 
+  
+      This API sends an event to the room. The server must ensure that the user
+      has permission to post events to this room.

 * ``operationId``: a camelCased unique identifier for this endpoint. This will
  be used to automatically generate bindings for the endpoint.