* Never use capital letters after `-`. Sentences start right after
the bullet and continue to the first period.
* When list elements are one or two sentences, use non-capitalized
format without terminators.
The two sentences are converted into one, separated by a semicolon.
This mainly applies to the cases with short sentences or when only
one of many list elements needs to have two sentences.
Example:
* `:opt_a` - basic description, no terminator
* `:opt_b` - also short description; this used to be second
sentence
* When at least one list element needs to have real sentences,
the whole list is formatted like that, with a period at the end
of each element:
* `:opt_a` - this is still short.
* `:opt_b` or `:opt_c` - but this is longer. May have multiple
sentences.
Or even paragraphs.
List items are marked with a star (*). Bullets marking list elements
must have a 2-space indent. The continuation lines should be indented
by 2 more spaces.
The second and subsequent paragraphs need to be indented 4 spaces
from the beginning of the line to be included in the list item.
The code fragments have to be indented 8 spaces from the beginning
of the line (or 4 spaces from the beginning of the preceding paragraph).
Sublists are marked with a hyphen (-). They follow the rules above
with the difference that their initial indent will be greater
(8 spaces from the beginning of the line).
Prior to this commit, Elixir allowed too many ambiguous calls
by ommitting the parentheses:
do_something 1, is_list [], 3
[1, is_atom :foo, 3]
Both cases above would lead to a compilation error, as an attempt
to call is_list/2 and is_atom/2 would happen. Those examples will
now raise a syntax error, pointing to the ambiguous location.
We have disallowed such examples throughout the language with
the exception of one argument calls:
assert is_list []
Examples as above are extremely frequent and were kept as is.
László Bácsi
Aleksei Magusev
Bruno Volcov
Eksperimental
José Valim
Michał Łępicki
Dan Rees-Jones
James Fish
Rich Morin
Lars Storjord
Alexei Sholik
Augie De Blieck Jr.
Igor Kapkov
José Valim
Yurii Rashkovskii