Fix common mistakes like the random backtick hanging in the wrong place,
or the wrongly formatted link, or single-quotes instead of backtick.
Commands to detect these common mistakes:
## COMMON MISTAKES
# single backtick in html docs
ag '`' ./doc --ignore "*.css" --ignore "*.js"
# links in the wrong format
ag '\[\w+://[^)\] ]+\]'
ag '\(\w+://[^)\] ]+\]'
ag '\[\w+://[^)\] ]+\)'
# find html code like: ["Strictly Pretty" (2000) by Christian Lindig][0]</p>
ag '\[[^\]]+\](\(|\[)' doc/ --ignore "*.js"
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"
It includes Erlang, Elixir, ExUnit, ExDoc, Logger, IEx, elixirc
It leaves Mix for a different PR.
Command to spot these words:
ag -s '(?<!(\`))(?<!(\.))(?<!(/))(?<!(:))(?<!(_))(erlang|elixir|eex|iex|ex_unit|ex_doc|logger|elixirc)(?!(:))(?!(\?))(?!(_))(?!(-))(?!(\.))(?!(\`))(?!(/))(?!(>))' \
--ignore "*.erl" --ignore "*.yrl" --ignore "*.src"
Corrects a few more cases that were not caught by the previous PR
https://github.com/elixir-lang/elixir/pull/3682
Command:
ignore_words="a|an|the|in|exception|helper|callback|front-end|same|when|where|what|functionality|elixir|erlang|eex|iex|logger|environment|module|similar|\w+-like|opposite|boolean|current|information|basic|public|if|unless|otherwise|regular|internal|convenience|given|welcome to|shortcut to|writable|user|system|low-level|pipe operator|supervisor|administrator"
ag "(@(module|short)?doc)\s+(~[Ss])?([\"']{3})(\r|\n|.)\s*+((?!((?i)${ignore_words}(?-i)))[\w'-]+)(?<!(s))(?<!(ed))(?<!(ity))(?<!(ally))(?<!(ily))(?<!(ely))(?=[\s\r\n,:.])"
This commits covers 100% of all links in the documentation,
using a words to describe what the page is about.
It users the `:module.function/arity` format for erlang functions that
link to the earlang docs.
I also changed some of the sentnces using the link from
- See [:erlang.function/2](http://...) for a list of available options.
to
- For a list of available options, see [:erlang.function/2](http://...)
The reasoning behind is that I think it's better to have an link at the end of the sentence
and not in the middle, so the reades doesn't need to finish the sentence to know what is it about and go back
and find the link. This way all the information is given before the link, so the users stops reading and can
click directly.
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"
It also removes the comment with doble ##,
So we can validate faulty indentation in iex>, ...>, ## with command:
# only 0, 2, 6, 10 spaces is valid for iex>, ...>, ##
ag "^(\ {1}|\ {3,5}|\ {7,9}|\ {11,100})(iex>|\.\.\.>|##)" --ignore "*.sh" --ignore "*.md" --ignore "lib/ex_unit/test/ex_unit/doc_test_test.exs"
just an update to https://github.com/elixir-lang/elixir/pull/3207
Command to detect missing backticks:
ag '^(?-m)[^\"\%\#\n]*\W(?m)(is|are|was|were|to|or|and|nor|when|returns?|defaults?|otherwise|\.)\s+(?-i)(true|false|nil)\W(?-m)'
It makes it consistent with the rest of the docs.
I have just looked for the first line in @doc, @moduledoc, so lines bellow it may still need
to be corrected.
@shortdoc all have been corrected.
Inspired by: https://github.com/elixir-lang/elixir/pull/2942
Command to list the first lines:
```sh
# first line in @moduledoc / @doc
ag '(@(module)?doc)\s+("{3})(\r|\n|.)\s*+[\w-]+(?<!s)\b'
# also @shortdoc
ag '(@shortdoc)\s+("{1,3})(\r|\n|.)\s*+[\w-]+(?<!s)\b'
```
Run the following command, and reviewed the occurences one by one.
# find words starting with vowels
ag -i '\ban?\s+[aeiou]\w+\b'
# find acronyms
ag '\ban?\s+[BCDFGHJKLMNPQRSTVWXYZ][A-Z]+\b'
# starting with "h"
ag -i '\ban?\s+[aeiou]\w+\b'
eksperimental
José Valim
José Valim
Gustavo Saiani
aforward
James Fish
Josh Adams