wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

doc style: lists

Browse source
This commit is contained in:
Richard van der Hoff 2018-02-06 17:30:22 +00:00 • committed by GitHub
parent 3c40d5a94e
commit 1028ea3558
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 8 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

10
meta/documentation_style.rst
View file

@ -62,13 +62,19 @@ have English as their first language.
Prefer British English (colour, -ise) to American English.
Lists should:
* Be introduced with a colon.
* Be used where they provide clarity.
* Contain entries which start with a capital and end with a full stop.
OpenAPI
~~~~~~~
When writing OpenAPI specifications for the API endpoints, follow these rules:
* ``summary``: a phrase summarising what this API does. Start with a capital,
end with a full-stop. Examples: "Sends an event."; "Searches the directory."
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.
@ -78,7 +84,7 @@ When writing OpenAPI specifications for the API endpoints, follow these rules:
* Parameter and property ``description``\s: a phrase summarising the behaviour
of this parameter or property, optionally followed by sentences giving more
detailed explanations.
detailed explanations. Start with a capital, end with a full stop.
The description is also the place to define default values for optional
properties. Use the wording "Defaults to X [if unspecified]."