From 196e6687681fb8529cd1065b364d20b7499ebfb6 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 14 Feb 2018 16:44:09 +0000 Subject: [PATCH] Update documentation_style.rst --- meta/documentation_style.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 6845e5da..54a74e0b 100644 --- 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.