This is a large commit that does the following:
* Removes backticks from messages and comments.
All references to backticks have been replaced with double quotes everywhere the
code is not interpreted as Markdown, (ie. anywhere outside documentation and
markdown files, such as in code comments, or error messages).
* Variables in Exception messages are printed using `inspect`
The way no-matching error message are printed, have changed because now we use inspect for printing
variables. The following file and their respective test have been changed:
- lib/elixir/lib/exception.ex
- lib/elixir/lib/inspect/algebra.ex
- lib/elixir/test/elixir/inspect_test.exs
- lib/ex_unit/test/ex_unit/formatter_test.exs
- lib/elixir/test/elixir/exception_test.exs
* Properly use Title Case for Mix, Git, Dializer
* Use backticks when citing a command
****************************************************
CONVENTION FOR RENAMING USING BACKTICKS AND QUOTES
https://github.com/elixir-lang/elixir/pull/3697#issuecomment-138811747
1. Backticks should never be printed in error messages, neither be included anywhere where Markdown code is not interpreted as such.
2. Do not use single quotes anywhere. We should favor double quotes everywhere, to avoid confusion
3. If you want to format something in error messages, use inspect. For example, if you want to show the dependency name and that is an atom, instead of the dependency "foo", let's show the dependency :foo. Less noise and may click better
4. Similarly, if you want to show something with double quotes, call inspect, as it handles escaping as well as the quotes
5. Things like "--all" just add verbosity, we can definitely read --all without ambiguity.
6. When using switches with a single hyphen (such as "-o"), we can make it explicit in the text: e.g. "... give the switch -o when choosing ..."
****************************************************
SHELL COMMANDS TO DETECT CODE BREAKING THE RULES
* Detect values surrounded by single-quotes where we want double-quotes.
# regular variables
ag "'#{"
# constants or ENV variables
ag "'[A-Z][A-Z0-9_-]+"
# switches
ag -i "(?<!(\[))'--?[a-z0-9][a-z0-9_-]+'"
# atoms
ag -i "(?<!(\[))':[a-z0-9][a-z0-9_-]+'"
# DETECT BACKTICKS OUTSIDE DOCS
ag "^\s+(?<!(#))#[^#\r\n]*\`" --ignore "*.md"
ag '^\s+["%].*`' --ignore "*.md"
ag -s '(raise|Error)\b(?!(`|/)).*\`'
* Spot mentions to running a command that is not using backticks:
commands="elixir|elixirc|mix|iex|ex_doc|git|make|rebar|dialyzer|erl|rm|cd|mkdir|rmdir|ln|ls|pwd"
actions="runs?|running|executes?|executing|types?|typing|enters?|entering|calls?|calling"
ag '(?i)('${actions}')(?-i)\b[^`\r\n/]+[\ \t]+(?!(`))('${commands}')'
ag '(?-i)\b(?!(`))('${commands}')[\ \t]+[^`\r\n/]+(?i)(commands?)'
* Spot where a command is mentioned:
#commands="erlang|elixir|eex|iex|ex_unit|ex_doc|logger|elixirc|git|make|rebar|dialyzer|erl|rm|cd|mkdir|rmdir|ln|ls|pwd"
commands="mix|elixirc|git|make|rebar|dialyzer|erl|rm|cd|mkdir|rmdir|ln|ls|pwd"
ag -s '(?<!(\`))(?<!(\.))(?<!(/))(?<!(:))(?<!(_))\b('${commands}')\b(?!(:))(?!(\?))(?!(_))(?!(-))(?!(\.))(?!(\`))(?!(/))(?!(>))' \
--ignore "*.erl" --ignore "*.yrl" --ignore "*.src"
Kernel.raise messages should not start with uppercase, and should not
have trailing punctuation.
Mix.raise messages should start with uppercase, and should not have a trailing
puntuation.
# starting with uppercase
# exclude (Mix.raise, and any message that starts with all uppecase such as: I or IO
ag '(?<!Mix\.)raise\s+\"+(?!([A-Z]+\b))[A-Z]'
# Mix.raise should start with upper case
# except when `mix` or `rebar` are mentioned
ag 'Mix\.raise\s+\"(?!(mix|rebar))+[a-z]'
# ending in period
ag "raise\s+\"+.+\.\"\s*\n"
removes the following warnings:
- test/ex_unit/assertions_test.exs:218: warning: variable x is unused
- test/ex_unit/assertions_test.exs:229: warning: variable x is unused
Currently doctests report the type and message of the raised exception,
but a synthetic stacktrace.
`assert_raise` does not provide any information about why
the wrong exception was raised, since the stacktrace points to test
line.
This change makes it display the original stacktrace too, which is more
useful for debugging and keeps symmetry with the information that
standard ExTests provide.
There is a bug in `doctest` with the `:only` option, such that it only works if
the list is of size 1. If you pass two functions to the option, `filter_by_opts`
will always be empty, since the function is checked with `Enum.all?`.
`Enum.any?` returns false for an empty list. Thus the extra `Enum.empty?` check.
Eric Entin
Andrea Leopardi
José Valim
eksperimental
Aleksei Magusev
José Valim
jisaacstone
Abel Muiño
Hubert Łępicki
Martin Svalin
Or Neeman
Lauro Caetano
Xavier Defrang