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)'
For the ones in the documentation, a space will be added in after the hyphen.
Just for consistency and to ease detection, I have replaced the ones in
comments as well.
Command to detect these lines:
ag "\w+-\n"
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'
José Valim
José Valim
eksperimental
Gustavo Saiani
Josh Crews
aforward
Eric Meadows-Jönsson