Rubocop: Add examples in the documentation

Created on 23 Oct 2017 · 10Comments · Source: rubocop-hq/rubocop

For a first step of contribution to RuboCop :star2:

For Japanese: https://qiita.com/pocke/items/ade84e1f21629220715d

Problem

RuboCop has many cops. But not all cops have examples in the documentation. So, sometime we can't understand easily how a cop to work.

Solution

We can add examples easily.
For instance, Layout/SpaceInsideParens had not had any examples, but examples ware added by this pull-request #4827.

We need to do only three things to add examples for a cop.
First, add examples to cop's source code as a comment.
For instance, I added examples to lib/rubocop/cop/layout/space_inside_parens.rb in the Layout/SpaceInsideParens case. We can use specs to add examples.

Second, run bundle exec rake generate_cops_documentation. The task generates the documentation to manual/ directory from the comments in source code.

Third, git commit and git push and send a pull-request!
Note: Do not add [Fix #4910] prefix to commit message. Because the prefix closes this issue.
Take care of Metrics/LineLength! You can check it with bundle exec rake internal_investigation.

List of cops that don't have examples yet.

The list is generated by the following one-liner automatically.

$ ruby -ractive_support -ractive_support/core_ext -e 'cops=`rubocop --show-cops`.scan(/^\w+\/\w+/); examples = `git grep @example`.scan(%r!\w+/\w+\.rb!).map{|e|e[%r!^(.+)\.rb!, 1].camelize.gsub("::",?/)}; puts cops.-(examples).grep_v(/RSpec|Capybara|FactoryBot/).map{|c|"- #{c}"}.join("\n")'

The list contains some cops that don't need examples. For example, I think Metrics cops don't need any examples. Long line example does not make sense.

[x] Layout/CommentIndentation
[x] Layout/EmptyLines
[x] Layout/EndOfLine
[x] Layout/IndentArray
[x] Layout/IndentHash
[x] Layout/InitialIndentation
[x] Layout/SpaceAfterSemicolon
[x] Layout/SpaceAroundEqualsInParameterDefault
[x] Layout/SpaceAroundOperators
[x] Layout/SpaceBeforeComma
[x] Layout/SpaceInsideBlockBraces
[x] Layout/SpaceInsideBrackets
[x] Layout/SpaceInsideHashLiteralBraces
[x] Layout/Tab
[x] Layout/TrailingBlankLines
[x] Layout/TrailingWhitespace
[x] Lint/ScriptPermission
[ ] Lint/Syntax
[x] Lint/UnneededDisable
[x] Naming/AsciiIdentifiers
[x] Naming/ClassAndModuleCamelCase
[x] Naming/ConstantName
[x] Naming/FileName
[x] Performance/FixedSize
[x] Performance/RangeInclude
[x] Rails/ActionFilter
[x] Rails/Exit
[x] Rails/HasAndBelongsToMany
[x] Rails/Output
[x] Rails/Validation
[x] Security/JSONLoad
[x] Security/YAMLLoad
[x] Style/ArrayJoin
[x] Style/AsciiComments
[x] Style/Attr
[x] Style/BarePercentLiterals
[ ] Style/BeginBlock
[x] Style/BlockComments
[x] Style/BlockDelimiters
[x] Style/CaseEquality
[x] Style/CharacterLiteral
[x] Style/ClassAndModuleChildren
[x] Style/ClassCheck
[x] Style/ClassVars
[ ] Style/CollectionMethods
[x] Style/ColonMethodCall
[x] Style/CommentAnnotation
[ ] Style/Copyright
[x] Style/DefWithParentheses
[x] Style/Documentation
[x] Style/EmptyLiteral
[x] Style/Encoding
[x] Style/EndBlock
[x] Style/FlipFlop
[x] Style/For
[x] Style/FormatString
[x] Style/FrozenStringLiteralComment
[x] Style/GlobalVars
[x] Style/IfUnlessModifier
[x] Style/IfWithSemicolon
[x] Style/MethodDefParentheses
[x] Style/MultilineTernaryOperator
[x] Style/NegatedWhile
[x] Style/NestedTernaryOperator
[x] Style/Not
[x] Style/NumericLiteralPrefix
[x] Style/OneLineConditional
[x] Style/ParenthesesAroundCondition
[x] Style/PercentQLiterals
[x] Style/PerlBackrefs
[x] Style/Proc
[x] Style/RedundantSelf
[x] Style/RescueModifier
[x] Style/Semicolon
[x] Style/Send
[x] Style/SignalException
[x] Style/SingleLineBlockParams
[x] Style/SingleLineMethods
[x] Style/SpecialGlobalVars
[x] Style/StringLiterals
[x] Style/StringMethods
[x] Style/TrivialAccessors
[x] Style/UnlessElse
[x] Style/UnneededCapitalW
[x] Style/UnneededPercentQ
[x] Style/VariableInterpolation
[x] Style/WhenThen
[x] Style/WhileUntilDo
[x] Style/WhileUntilModifier

documentation good first issue high priority

Source

pocke

❤10 👍4

All 10 comments

@pocke: I added checkboxes to your list, and removed the Metric ones. Hope that's okay. 🙂

Drenmi on 23 Oct 2017

👍1

@pocke I missed the commit message #4910 and closed this Issue. However 35 cops still have no document.

% ruby -ractive_support -ractive_support/core_ext -e 'cops=`rubocop --show-cops`.scan(/^\w+\/\w+/); examples = `git grep @example`.scan(%r!\w+/\w+\.rb!).map{|e|e[%r!^(.+)\.rb!, 1].camelize.gsub("::",?/)}; puts cops.-(examples).grep_v(/RSpec|Capybara|FactoryGirl/).map{|c|"- #{c}"}.join("\n")' | wc -l
      35

Would you please re-opening this Issue?

koic on 6 Jan 2018

👍1

Reopened. Thank you!

pocke on 7 Jan 2018

❤1

I went to add documentation to Layout/InitialIndentation and it appears that an example already exists.

mmanousos on 25 Mar 2018

Lint/ScriptPermission already has an example as a comment in script_permission.rb

janelle-gatchalian on 25 Mar 2018

JSONLoad looks like it's already been documented.

oedalis on 25 Mar 2018

Layout/SpaceAroundOperators as well has already been documented, can be checked off of the list above

niamurrell on 25 Mar 2018

It would be great if the step for running tests ("Run rake default or rake parallel. It executes all tests and RuboCop for itself, and generates the documentation.") was part of the steps above and not only present in the PR checklist.

mmanousos on 25 Mar 2018

Thanks all! I've updated the checklist.

pocke on 25 Mar 2018

I guess we can close this one now.