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. 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 OpenAPI
~~~~~~~ ~~~~~~~
When writing OpenAPI specifications for the API endpoints, follow these rules: When writing OpenAPI specifications for the API endpoints, follow these rules:
* ``summary``: a phrase summarising what this API does. Start with a capital, * ``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 * ``description``: a longer description of the behaviour of this API, written
in complete sentences. 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 * Parameter and property ``description``\s: a phrase summarising the behaviour
of this parameter or property, optionally followed by sentences giving more 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 The description is also the place to define default values for optional
properties. Use the wording "Defaults to X [if unspecified]." properties. Use the wording "Defaults to X [if unspecified]."