rubocop-solidus 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 745ca1ca12310bb9de934135f03aae227d87d616005ce5e82aafe58d6554a88d
-  data.tar.gz: 9723caf52452c8b1d4fa8bf88f644298bda3d01631af85df95a6aceb6b741462
+  metadata.gz: df0c66e0a5dddaec3401e5cfd7d4f2704d0d920d9883172e7d8551aee6663641
+  data.tar.gz: 929b18aba23c67ae33c3582d94e3758a6682668cfe8595e49107e72387672050
 SHA512:
-  metadata.gz: 8683bf3a98d2483a25e1d18a078ca9a44ad39eb138a069364b664dbdc989f0199a7bcb86c68ce750268a310ca0c0342cc4cd55a60448edc65d3ff9b3a28e56f8
-  data.tar.gz: 2c36b5f8362baf576f3eaecc05e63324d988f1fcf0a0d63ce27c606787437a8fd303e8ca1172269f7766de26378d6aaf2598831dcbf43eef5583551f2581177a
+  metadata.gz: de6813fbc0de1c6e24bc686622112ba91d71580a5d116f4eb33747ffeceef4c74fc437dc31c5b98a209f592b4bd5fb970be8495b7a04e98515fc262fd7497edf
+  data.tar.gz: 619bf635aa925403cdce3fcf65f9be39b45d5d301348eb2c6666f5b48e9f45b16cc9d22c7b641f5906f19991ca4ffe2a721b6643677cac458288af02c440fd18

data/.rubocop.yml

@@ -2,6 +2,7 @@ inherit_from: .rubocop_todo.yml
 
 AllCops:
   NewCops: enable
+  SuggestExtensions: false
 
 Naming/FileName:
  Exclude:
@@ -14,6 +15,13 @@ Metrics/BlockLength:
     - 'spec/**/*.rb'
     - '*.gemspec'
 
+Metrics/MethodLength:
+  Exclude:
+    - 'Rakefile'
+    - '**/*.rake'
+    - 'spec/**/*.rb'
+    - '*.gemspec'
+
 Metrics/ClassLength:
   Exclude:
     - 'tasks/**/*.rb'

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## master (unreleased)
 
+## 0.1.4 (2023-08-04)
+
+### New features
+
+* [#51](https://github.com/solidusio/rubocop-solidus/pull/51): Create automatic documentation based on the cop's descriptions. ([@MassimilianoLattanzio][])
+
 ## 0.1.3 (2023-07-28)
 
 ### New features

data/Gemfile

@@ -10,3 +10,4 @@ gem 'pry'
 gem 'rake'
 gem 'rspec'
 gem 'rubocop'
+gem 'yard'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rubocop-solidus (0.1.3)
+    rubocop-solidus (0.1.4)
       rubocop
 
 GEM
@@ -54,6 +54,7 @@ GEM
       parser (>= 3.2.1.0)
     ruby-progressbar (1.13.0)
     unicode-display_width (2.4.2)
+    yard (0.9.34)
 
 PLATFORMS
   -darwin-22
@@ -69,6 +70,7 @@ DEPENDENCIES
   rspec
   rubocop
   rubocop-solidus!
+  yard
 
 BUNDLED WITH
    2.3.26

data/README.md

@@ -3,12 +3,14 @@
 Automatic Solidus code style checking tool.
 A RuboCop extension focused on enforcing Solidus best practices and coding conventions.
 
-## Installation
+## Getting started
+
+### Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'rubocop-solidus' require: false
+gem 'rubocop-solidus', require: false
 ```
 
 And then execute:
@@ -19,7 +21,7 @@ Or install it yourself as:
 
     $ gem install rubocop-solidus
 
-## Usage
+### Usage
 
 To Start using this extension in your application add the following lines to your `.rubocop.yml` file
 
@@ -30,7 +32,17 @@ require:
 
 After this simply use the `rubocop` command to start linting.
 
-## Creating new cops
+## Documentation
+
+You can read about each cop supplied by RuboCop Solidus in [the docs](docs/cops.md).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/solidusio/rubocop-solidus.
+
+To contribute a new cop, please see the sections below.
+
+### Creating new cops
 
 To create a new cop, run the following command:
 
@@ -40,7 +52,7 @@ $ bundle exec rake 'new_cop[Solidus/NameOfTheCop]'
 
 and then follow the instructions on the screen.
 
-## Creating changelog entries
+### Creating changelog entries
 
 Changelog entries are just files under the `changelog/` folder that will be merged
 into `CHANGELOG.md` at release time. You can create new changelog entries like this:
@@ -51,7 +63,7 @@ $ bundle exec rake changelog:new|fix|change
 
 The type of the changelog correspond to "new feature", "bug-fix" and "changed" entries in the changelog.
 
-### Changelog entry format
+#### Changelog entry format
 
 Here are a few examples:
 
@@ -68,7 +80,7 @@ Here are a few examples:
 * If this is a breaking change, mark it with `**(Breaking)**`.
 * At the end of the entry, add an implicit link to your GitHub user page as `([@username][])`.
 
-## Release a new version
+### Release a new version
 
 To release a new version, run the following command:
 
@@ -89,10 +101,6 @@ To deploy the new version to RubyGems, run the following command:
 $ bundle exec rake release
 ```
 
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/solidusio/rubocop-solidus.
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -6,7 +6,12 @@ require 'rspec/core/rake_task'
 
 Dir['tasks/**/*.rake'].each { |t| load t }
 
-task default: %i[spec rubocop]
+task default: %i[
+  spec
+  rubocop
+  generate_cops_documentation
+  documentation_syntax_check
+]
 
 RuboCop::RakeTask.new
 

data/docs/cops.md

@@ -0,0 +1,19 @@
+## Available cops
+
+In the following section you find all available cops:
+
+<!-- START_COP_LIST -->
+#### Department [Solidus](cops_solidus.md)
+
+* [Solidus/ClassEvalDecorator](cops_solidus.md#solidusclassevaldecorator)
+* [Solidus/ReimbursementHookDeprecated](cops_solidus.md#solidusreimbursementhookdeprecated)
+* [Solidus/SpreeCalculatorFreeShippingDeprecated](cops_solidus.md#solidusspreecalculatorfreeshippingdeprecated)
+* [Solidus/SpreeCalculatorPercentPerItemDeprecated](cops_solidus.md#solidusspreecalculatorpercentperitemdeprecated)
+* [Solidus/SpreeCalculatorPriceSackDeprecated](cops_solidus.md#solidusspreecalculatorpricesackdeprecated)
+* [Solidus/SpreeDefaultCreditCardDeprecated](cops_solidus.md#solidusspreedefaultcreditcarddeprecated)
+* [Solidus/SpreeGatewayBogusDeprecated](cops_solidus.md#solidusspreegatewaybogusdeprecated)
+* [Solidus/SpreeIconDeprecated](cops_solidus.md#solidusspreeicondeprecated)
+* [Solidus/SpreeRefundCallPerform](cops_solidus.md#solidusspreerefundcallperform)
+* [Solidus/SpreeTDeprecated](cops_solidus.md#solidusspreetdeprecated)
+
+<!-- END_COP_LIST -->

data/docs/cops_solidus.md

@@ -0,0 +1,276 @@
+# Solidus
+
+## Solidus/ClassEvalDecorator
+
+Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version
+--- | --- | --- | --- | --- | ---
+Enabled | Yes | No | 0.1.0 | - | -
+
+Solidus suggests a decorator module instead of `class_eval` when overriding some features.
+This cop finds any `class_eval` and asks to use a decorator module instead.
+More info: https://guides.solidus.io/customization/customizing-the-core.
+
+### Examples
+
+```ruby
+# bad
+SpreeClass.class_eval do
+  # your code here
+end
+
+# good
+module Spree
+  module SpreeClassDecorator
+    # your code here
+  end
+
+  Spree::SpreeClass.prepend self
+end
+```
+
+### References
+
+* [https://github.com/solidusio/rubocop-solidus/issues/21](https://github.com/solidusio/rubocop-solidus/issues/21)
+
+## Solidus/ReimbursementHookDeprecated
+
+Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version
+--- | --- | --- | --- | --- | ---
+Enabled | Yes | No | 0.1.0 | - | 2.11
+
+This cop finds reimbursement_success_hooks and reimbursement_failed_hooks calls and
+asks to remove them and subscribe to reimbursement_reimbursed event instead.
+
+### Examples
+
+```ruby
+# bad
+reimbursement_success_hooks.each { |h| h.call self }
+reimbursement_failed_hooks.each { |h| h.call self }
+
+# good
+```
+```ruby
+# bad
+reimbursement_success_hooks.any?
+reimbursement_failed_hooks.any?
+
+# good
+```
+
+### References
+
+* [https://github.com/solidusio/rubocop-solidus/issues/27](https://github.com/solidusio/rubocop-solidus/issues/27)
+
+## Solidus/SpreeCalculatorFreeShippingDeprecated
+
+Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version
+--- | --- | --- | --- | --- | ---
+Enabled | Yes | No | 0.1.0 | - | -
+
+This cop finds Spree::Calculator::FreeShipping calls.
+This cop is needed as they have been deprecated in future version.
+
+### Examples
+
+```ruby
+# bad
+Spree::Calculator::FreeShipping
+
+# good
+```
+
+### References
+
+* [https://github.com/solidusio/rubocop-solidus/issues/29](https://github.com/solidusio/rubocop-solidus/issues/29)
+
+## Solidus/SpreeCalculatorPercentPerItemDeprecated
+
+Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version
+--- | --- | --- | --- | --- | ---
+Enabled | Yes | Yes  | 0.1.0 | - | -
+
+This cop finds Spree::Calculator::PercentPerItem calls.
+This cop is needed as they have been deprecated in future version.
+
+### Examples
+
+```ruby
+# bad
+Spree::Calculator::PercentPerItem
+
+# good
+Spree::Calculator::PercentOnLineItem
+```
+
+### References
+
+* [https://github.com/solidusio/rubocop-solidus/issues/29](https://github.com/solidusio/rubocop-solidus/issues/29)
+
+## Solidus/SpreeCalculatorPriceSackDeprecated
+
+Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version
+--- | --- | --- | --- | --- | ---
+Enabled | Yes | No | 0.1.0 | - | -
+
+This cop finds Spree::Calculator::PriceSack calls.
+This cop is needed as they have been deprecated in future version.
+
+### Examples
+
+```ruby
+# bad
+Spree::Calculator::PriceSack
+
+# good
+```
+
+### References
+
+* [https://github.com/solidusio/rubocop-solidus/issues/29](https://github.com/solidusio/rubocop-solidus/issues/29)
+
+## Solidus/SpreeDefaultCreditCardDeprecated
+
+Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version
+--- | --- | --- | --- | --- | ---
+Enabled | Yes | Yes  | 0.1.0 | - | 2.2
+
+This cop finds user.default_credit_card suggest using user.wallet.default_wallet_payment_source.
+
+### Examples
+
+```ruby
+# bad
+user.default_credit_card
+
+# good
+user.wallet.default_wallet_payment_source
+```
+
+### References
+
+* [https://github.com/solidusio/rubocop-solidus/issues/33](https://github.com/solidusio/rubocop-solidus/issues/33)
+
+## Solidus/SpreeGatewayBogusDeprecated
+
+Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version
+--- | --- | --- | --- | --- | ---
+Enabled | Yes | Yes  | 0.1.0 | - | 2.1
+
+This cop finds Spree::Gateway::Bogus calls and replaces them with the Spree::PaymentMethod::BogusCreditCard.
+This cop is needed as the Spree::Gateway::Bogus has been deprecated in future version.
+
+### Examples
+
+```ruby
+# bad
+Spree::Gateway::Bogus.new
+Spree::Gateway::Bogus.create
+Spree::Gateway::Bogus.create!
+
+# good
+Spree::PaymentMethod::BogusCreditCard.new
+Spree::PaymentMethod::BogusCreditCard.create
+Spree::PaymentMethod::BogusCreditCard.create!
+```
+
+### References
+
+* [https://github.com/solidusio/rubocop-solidus/issues/26](https://github.com/solidusio/rubocop-solidus/issues/26)
+
+## Solidus/SpreeIconDeprecated
+
+Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version
+--- | --- | --- | --- | --- | ---
+Enabled | Yes | Yes  | 0.1.0 | - | 2.3
+
+This cop finds icon helper calls and suggest using solidus_icon.
+
+### Examples
+
+```ruby
+# bad
+helper.icon('example')
+
+# good
+helper.solidus_icon('example')
+```
+
+### References
+
+* [https://github.com/solidusio/rubocop-solidus/issues/32](https://github.com/solidusio/rubocop-solidus/issues/32)
+
+## Solidus/SpreeRefundCallPerform
+
+Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version
+--- | --- | --- | --- | --- | ---
+Enabled | Yes | No | 0.1.0 | - | 2.11
+
+This cop finds Spree::Refund.create(your: attributes) calls and
+replaces them with the Spree::Refund.create(your: attributes, perform_after_create: false).perform! call.
+
+### Examples
+
+```ruby
+# bad
+Spree::Refund.create(your: attributes)
+
+# good
+Spree::Refund.create(your: attributes, perform_after_create: false).perform!
+```
+
+### References
+
+* [https://github.com/solidusio/rubocop-solidus/issues/28](https://github.com/solidusio/rubocop-solidus/issues/28)
+
+## Solidus/SpreeTDeprecated
+
+Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version
+--- | --- | --- | --- | --- | ---
+Enabled | Yes | Yes  | 0.1.0 | - | -
+
+This cop finds Spree.t method calls and replaces them with the I18n,t method call.
+This cop is needed as the Spree.t version has been deprecated in future version.
+
+### Examples
+
+```ruby
+# Without any parameters
+
+# bad
+Spree.t(:bar)
+
+# good
+I18n.t(:bar, scope: :spree)
+```
+```ruby
+# With the scope parameter
+
+# bad
+Spree.t(:bar, scope: [:city])
+
+# good
+I18n.t(:bar, scope: [:spree, :city])
+```
+```ruby
+# With the scope and other parameters
+
+# bad
+Spree.t(:bar, scope: [:city], email: email)
+
+# good
+I18n.t(:bar, scope: [:spree, :city], email: email)
+```
+```ruby
+# With the scope parameter as a string
+
+# bad
+Spree.t('bar', scope: 'admin.city')
+
+# good
+I18n.t('bar', scope: 'spree.admin.city')
+```
+
+### References
+
+* [https://github.com/solidusio/rubocop-solidus/issues/22](https://github.com/solidusio/rubocop-solidus/issues/22)

data/lib/rubocop/cop/mixin/target_solidus_version.rb

@@ -24,6 +24,10 @@ module RuboCop
         def targeted_solidus_version?(version)
           Gem::Version.new(@minimum_solidus_version) <= Gem::Version.new(version)
         end
+
+        def required_minimum_solidus_version
+          @minimum_solidus_version
+        end
       end
 
       # This method overrides the one in RuboCop::Cop::Base.

data/lib/rubocop/cop/solidus/class_eval_decorator.rb

@@ -3,35 +3,31 @@
 module RuboCop
   module Cop
     module Solidus
-      # TODO: Write cop description and example of bad / good code. For every
-      # `SupportedStyle` and unique configuration, there needs to be examples.
-      # Examples must have valid Ruby syntax. Do not use upticks.
+      # Solidus suggests a decorator module instead of `class_eval` when overriding some features.
+      # This cop finds any `class_eval` and asks to use a decorator module instead.
+      # More info: https://guides.solidus.io/customization/customizing-the-core.
       #
-      #
-      # @example EnforcedStyle: SpreeClass
-      #   # Description of the `SpreeClass` style.
+      # @example
       #
       #   # bad
       #   SpreeClass.class_eval do
-      #   .
-      #   .
+      #     # your code here
       #   end
       #
-      #
       #   # good
-      #   module SpreeClassDecorator
-      #   .
-      #   .
+      #   module Spree
+      #     module SpreeClassDecorator
+      #       # your code here
+      #     end
+      #
+      #     Spree::SpreeClass.prepend self
       #   end
       #
       class ClassEvalDecorator < Base
-        MSG = 'Do not use `class_eval` flag. Use a decorator module instead. Check this link for an example https://guides.solidus.io/cookbook/redefining-checkout-steps'
+        MSG = 'Do not use `class_eval` flag. Use a decorator module instead. More info: https://guides.solidus.io/customization/customizing-the-core.'
 
-        # TODO: Don't call `on_send` unless the method name is in this list
-        # If you don't need `on_send` in the cop you created, remove it.
         RESTRICT_ON_SEND = %i[class_eval].freeze
 
-        # @!method on_class_eval?(node)
         def_node_matcher :on_class_eval?, <<~PATTERN
           (send  ($...) :class_eval)
         PATTERN

data/lib/rubocop/cop/solidus/reimbursement_hook_deprecated.rb

@@ -5,6 +5,23 @@ module RuboCop
     module Solidus
       # This cop finds reimbursement_success_hooks and reimbursement_failed_hooks calls and
       # asks to remove them and subscribe to reimbursement_reimbursed event instead.
+      #
+      # @example
+      #
+      #   # bad
+      #   reimbursement_success_hooks.each { |h| h.call self }
+      #   reimbursement_failed_hooks.each { |h| h.call self }
+      #
+      #   # good
+      #
+      # @example
+      #
+      #   # bad
+      #   reimbursement_success_hooks.any?
+      #   reimbursement_failed_hooks.any?
+      #
+      #   # good
+      #
       class ReimbursementHookDeprecated < Base
         include TargetSolidusVersion
         minimum_solidus_version 2.11

data/lib/rubocop/cop/solidus/spree_calculator_free_shipping_deprecated.rb

@@ -6,6 +6,13 @@ module RuboCop
       # This cop finds Spree::Calculator::FreeShipping calls.
       # This cop is needed as they have been deprecated in future version.
       #
+      # @example
+      #
+      #   # bad
+      #   Spree::Calculator::FreeShipping
+      #
+      #   # good
+      #
       class SpreeCalculatorFreeShippingDeprecated < Base
         MSG = 'Spree::Calculator::FreeShipping is deprecated.'
 

data/lib/rubocop/cop/solidus/spree_calculator_percent_per_item_deprecated.rb

@@ -6,10 +6,18 @@ module RuboCop
       # This cop finds Spree::Calculator::PercentPerItem calls.
       # This cop is needed as they have been deprecated in future version.
       #
+      # @example
+      #
+      #   # bad
+      #   Spree::Calculator::PercentPerItem
+      #
+      #   # good
+      #   Spree::Calculator::PercentOnLineItem
+      #
       class SpreeCalculatorPercentPerItemDeprecated < Base
         extend AutoCorrector
 
-        MSG = 'Spree::Calculator::PercentPerItem is deprecated.'
+        MSG = 'Spree::Calculator::PercentPerItem is deprecated. Use Spree::Calculator::PercentOnLineItem instead.'
 
         def_node_matcher :percent_per_item?, <<~PATTERN
           (send (... (... :Calculator) :PercentPerItem) $_)

data/lib/rubocop/cop/solidus/spree_calculator_price_sack_deprecated.rb

@@ -6,6 +6,13 @@ module RuboCop
       # This cop finds Spree::Calculator::PriceSack calls.
       # This cop is needed as they have been deprecated in future version.
       #
+      # @example
+      #
+      #   # bad
+      #   Spree::Calculator::PriceSack
+      #
+      #   # good
+      #
       class SpreeCalculatorPriceSackDeprecated < Base
         MSG = 'Spree::Calculator::PriceSack is deprecated.'
 

data/lib/rubocop/cop/solidus/spree_default_credit_card_deprecated.rb

@@ -3,16 +3,16 @@
 module RuboCop
   module Cop
     module Solidus
-      # This cop finds user.default_credit_card suggest using user.wallet.default_wallet_payment_source
+      # This cop finds user.default_credit_card suggest using user.wallet.default_wallet_payment_source.
+      #
+      # @example
       #
-      # @example EnforcedStyle:
       #   # bad
       #   user.default_credit_card
       #
       #   # good
       #   user.wallet.default_wallet_payment_source
       #
-      #
       class SpreeDefaultCreditCardDeprecated < Base
         extend AutoCorrector
         include TargetSolidusVersion
@@ -20,7 +20,6 @@ module RuboCop
 
         MSG = 'user.default_credit_card is deprecated. Please use user.wallet.default_wallet_payment_source instead.'
 
-        # @!method bad_method?(node)
         def_node_matcher :default_credit_card?, <<~PATTERN
           (send ... :default_credit_card)
         PATTERN

data/lib/rubocop/cop/solidus/spree_gateway_bogus_deprecated.rb

@@ -3,29 +3,20 @@
 module RuboCop
   module Cop
     module Solidus
-      # This cop finds Spree::Gateway::Bogus calls and replaces them with the Spree::PaymentMethod::BogusCreditCard call
+      # This cop finds Spree::Gateway::Bogus calls and replaces them with the Spree::PaymentMethod::BogusCreditCard.
       # This cop is needed as the Spree::Gateway::Bogus has been deprecated in future version.
       #
-      # @example EnforcedStyle:
+      # @example
       #   # bad
       #   Spree::Gateway::Bogus.new
-      #
-      #   # good
-      #   Spree::PaymentMethod::BogusCreditCard.new
-      #
-      #   # bad
       #   Spree::Gateway::Bogus.create
-      #
-      #   # good
-      #   Spree::PaymentMethod::BogusCreditCard.create
-      #
-      #   # bad
       #   Spree::Gateway::Bogus.create!
       #
       #   # good
+      #   Spree::PaymentMethod::BogusCreditCard.new
+      #   Spree::PaymentMethod::BogusCreditCard.create
       #   Spree::PaymentMethod::BogusCreditCard.create!
       #
-      #
       class SpreeGatewayBogusDeprecated < Base
         extend AutoCorrector
         include TargetSolidusVersion
@@ -33,7 +24,6 @@ module RuboCop
 
         MSG = 'Spree::Gateway::Bogus is deprecated. Please use Spree::PaymentMethod::BogusCreditCard instead.'
 
-        # @!method bad_method?(node)
         def_node_matcher :bad_class?, <<~PATTERN
           (send (... (... :Gateway) :Bogus) $_)
         PATTERN

data/lib/rubocop/cop/solidus/spree_icon_deprecated.rb

@@ -3,16 +3,16 @@
 module RuboCop
   module Cop
     module Solidus
-      # This cop finds icon helper calls and suggest using solidus_icon
+      # This cop finds icon helper calls and suggest using solidus_icon.
+      #
+      # @example
       #
-      # @example EnforcedStyle:
       #   # bad
       #   helper.icon('example')
       #
       #   # good
       #   helper.solidus_icon('example')
       #
-      #
       class SpreeIconDeprecated < Base
         extend AutoCorrector
         include TargetSolidusVersion

data/lib/rubocop/cop/solidus/spree_refund_call_perform.rb

@@ -4,7 +4,15 @@ module RuboCop
   module Cop
     module Solidus
       # This cop finds Spree::Refund.create(your: attributes) calls and
-      # replaces them with the Spree::Refund.create(your: attributes, perform_after_create: false).perform! call
+      # replaces them with the Spree::Refund.create(your: attributes, perform_after_create: false).perform! call.
+      #
+      # @example
+      #
+      #   # bad
+      #   Spree::Refund.create(your: attributes)
+      #
+      #   # good
+      #   Spree::Refund.create(your: attributes, perform_after_create: false).perform!
       #
       class SpreeRefundCallPerform < Base
         include TargetSolidusVersion
@@ -16,7 +24,6 @@ module RuboCop
 
         RESTRICT_ON_SEND = %i[create].freeze
 
-        # @!method bad_method?(node)
         def_node_matcher :create_refund?, <<~PATTERN
           (send (const (const nil? :Spree) :Refund) :create ...)
         PATTERN

data/lib/rubocop/cop/solidus/spree_t_deprecated.rb

@@ -3,43 +3,51 @@
 module RuboCop
   module Cop
     module Solidus
-      # This cop finds Spree.t method calls and replaces them with the I18n,t method call
+      # This cop finds Spree.t method calls and replaces them with the I18n,t method call.
       # This cop is needed as the Spree.t version has been deprecated in future version.
       #
+      # @example
+      #   # Without any parameters
       #
-      # @example EnforcedStyle: bar (default)
       #   # bad
       #   Spree.t(:bar)
       #
       #   # good
       #   I18n.t(:bar, scope: :spree)
       #
+      # @example
+      #   # With the scope parameter
+      #
       #   # bad
       #   Spree.t(:bar, scope: [:city])
       #
       #   # good
       #   I18n.t(:bar, scope: [:spree, :city])
       #
+      # @example
+      #   # With the scope and other parameters
+      #
       #   # bad
       #   Spree.t(:bar, scope: [:city], email: email)
       #
       #   # good
       #   I18n.t(:bar, scope: [:spree, :city], email: email)
       #
+      # @example
+      #   # With the scope parameter as a string
+      #
       #   # bad
       #   Spree.t('bar', scope: 'admin.city')
       #
       #   # good
       #   I18n.t('bar', scope: 'spree.admin.city')
       #
-      #
       class SpreeTDeprecated < Base
         extend AutoCorrector
         MSG = 'Use I18n.t instead of Spree.t which has been deprecated in future versions.'
 
         RESTRICT_ON_SEND = %i[t].freeze
 
-        # @!method spree_t?(node)
         def_node_matcher :spree_t?, <<~PATTERN
           (send ($...) :t ...)
         PATTERN

data/lib/rubocop/solidus/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Solidus
-    VERSION = '0.1.3'
+    VERSION = '0.1.4'
   end
 end

data/relnotes/v0.1.4.md

@@ -0,0 +1,5 @@
+### New features
+
+* [#51](https://github.com/solidusio/rubocop-solidus/pull/51): Create automatic documentation based on the cop's descriptions. ([@MassimilianoLattanzio][])
+
+[@MassimilianoLattanzio]: https://github.com/MassimilianoLattanzio

data/rubocop-solidus.gemspec

@@ -19,7 +19,8 @@ Gem::Specification.new do |spec|
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://www.github.com/solidusio/rubocop-solidus'
-  spec.metadata['changelog_uri'] = 'https://www.github.com/solidusio/rubocop-solidus'
+  spec.metadata['changelog_uri'] = 'https://www.github.com/solidusio/rubocop-solidus/blob/master/CHANGELOG.md'
+  spec.metadata['documentation_uri'] = 'https://www.github.com/solidusio/rubocop-solidus/blob/master/docs/cops.md'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

data/tasks/cops_documentation.rake

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require 'yard'
+require 'rubocop'
+require 'rubocop-solidus'
+
+YARD::Rake::YardocTask.new(:yard_for_generate_documentation) do |task|
+  task.files = ['lib/rubocop/cop/**/*.rb']
+  task.options = ['--no-output']
+end
+
+desc('Generate docs of all cops departments')
+task generate_cops_documentation: :yard_for_generate_documentation do
+  def cops_of_department(cops, department)
+    cops.with_department(department).sort!
+  end
+
+  def cops_body(config, cop, description, examples_objects, pars)
+    content = h2(cop.cop_name)
+    content << required_ruby_version(cop)
+    content << properties(config, cop)
+    content << "#{description}\n"
+    content << examples(examples_objects) if examples_objects.count.positive?
+    content << configurations(pars)
+    content << references(config, cop)
+    content
+  end
+
+  def examples(examples_object)
+    examples_object.each_with_object(h3('Examples').dup) do |example, content|
+      content << h4(example.name) unless example.name == ''
+      content << code_example(example)
+    end
+  end
+
+  def required_ruby_version(cop)
+    return '' unless cop.respond_to?(:required_minimum_ruby_version)
+
+    <<~NOTE
+      !!! Note
+
+          Required Ruby version: #{cop.required_minimum_ruby_version}
+
+    NOTE
+  end
+
+  def properties(config, cop)
+    header = [
+      'Enabled by default', 'Safe', 'Supports autocorrection', 'VersionAdded',
+      'VersionChanged', 'Required Solidus Version'
+    ]
+    config = config.for_cop(cop)
+    safe_auto_correct = config.fetch('SafeAutoCorrect', true)
+    autocorrect = if cop.support_autocorrect?
+                    "Yes #{'(Unsafe)' unless safe_auto_correct}"
+                  else
+                    'No'
+                  end
+    minimum_solidus_version = if cop.respond_to?(:required_minimum_solidus_version)
+                                cop.required_minimum_solidus_version
+                              else
+                                '-'
+                              end
+    content = [[
+      config.fetch('Enabled') ? 'Enabled' : 'Disabled',
+      config.fetch('Safe', true) ? 'Yes' : 'No',
+      autocorrect,
+      config.fetch('VersionAdded', '-'),
+      config.fetch('VersionChanged', '-'),
+      minimum_solidus_version
+    ]]
+    "#{to_table(header, content)}\n"
+  end
+
+  def h2(title)
+    content = +"\n"
+    content << "## #{title}\n"
+    content << "\n"
+    content
+  end
+
+  def h3(title)
+    content = +"\n"
+    content << "### #{title}\n"
+    content << "\n"
+    content
+  end
+
+  def h4(title)
+    content = +"#### #{title}\n"
+    content << "\n"
+    content
+  end
+
+  def code_example(ruby_code)
+    content = +"```ruby\n"
+    content << ruby_code.text
+                        .gsub('@good', '# good').gsub('@bad', '# bad').strip
+    content << "\n```\n"
+    content
+  end
+
+  def configurations(pars)
+    return '' if pars.empty?
+
+    header = ['Name', 'Default value', 'Configurable values']
+    configs = pars.each_key.reject { |key| key.start_with?('Supported') }
+    content = configs.map do |name|
+      configurable = configurable_values(pars, name)
+      default = format_table_value(pars[name])
+      [name, default, configurable]
+    end
+
+    h3('Configurable attributes') + to_table(header, content)
+  end
+
+  # rubocop:disable Metrics/CyclomaticComplexity
+  def configurable_values(pars, name)
+    case name
+    when /^Enforced/
+      supported_style_name = RuboCop::Cop::Util.to_supported_styles(name)
+      format_table_value(pars[supported_style_name])
+    when 'IndentationWidth'
+      'Integer'
+    when 'Database'
+      format_table_value(pars['SupportedDatabases'])
+    else
+      case pars[name]
+      when String
+        'String'
+      when Integer
+        'Integer'
+      when Float
+        'Float'
+      when true, false
+        'Boolean'
+      when Array
+        'Array'
+      else
+        ''
+      end
+    end
+  end
+  # rubocop:enable Metrics/CyclomaticComplexity
+
+  def to_table(header, content)
+    table = [
+      header.join(' | '),
+      Array.new(header.size, '---').join(' | ')
+    ]
+    table.concat(content.map { |c| c.join(' | ') })
+    "#{table.join("\n")}\n"
+  end
+
+  def format_table_value(val)
+    value =
+      case val
+      when Array
+        if val.empty?
+          '`[]`'
+        else
+          val.map { |config| format_table_value(config) }.join(', ')
+        end
+      else
+        "`#{val.nil? ? '<none>' : val}`"
+      end
+    value.gsub("#{Dir.pwd}/", '').rstrip
+  end
+
+  def references(config, cop)
+    cop_config = config.for_cop(cop)
+    urls = RuboCop::Cop::MessageAnnotator.new(
+      config, cop.name, cop_config, {}
+    ).urls
+    return '' if urls.empty?
+
+    content = h3('References')
+    content << urls.map { |url| "* [#{url}](#{url})" }.join("\n")
+    content << "\n"
+    content
+  end
+
+  def print_cops_of_department(cops, department, config)
+    selected_cops = cops_of_department(cops, department).select do |cop|
+      cop.to_s.start_with?('RuboCop::Cop::Solidus')
+    end
+    return if selected_cops.empty?
+
+    content = +"# #{department}\n"
+    selected_cops.each do |cop|
+      content << print_cop_with_doc(cop, config)
+    end
+    file_name = "#{Dir.pwd}/docs/cops_#{department.downcase}.md"
+    File.open(file_name, 'w') do |file|
+      puts "* generated #{file_name}"
+      file.write("#{content.strip}\n")
+    end
+  end
+
+  def print_cop_with_doc(cop, config)
+    t = config.for_cop(cop)
+    non_display_keys = %w[Description Enabled StyleGuide Reference Safe SafeAutoCorrect VersionAdded
+                          VersionChanged]
+    pars = t.reject { |k| non_display_keys.include?(k) }
+    description = 'No documentation'
+    examples_object = []
+    YARD::Registry.all(:class).detect do |code_object|
+      next unless RuboCop::Cop::Badge.for(code_object.to_s) == cop.badge
+
+      description = code_object.docstring unless code_object.docstring.blank?
+      examples_object = code_object.tags('example')
+    end
+    cops_body(config, cop, description, examples_object, pars)
+  end
+
+  # rubocop:disable Metrics/AbcSize
+  def table_of_content_for_department(cops, department)
+    selected_cops = cops_of_department(cops, department.to_sym).select do |cop|
+      cop.to_s.start_with?('RuboCop::Cop::Solidus')
+    end
+    return if selected_cops.empty?
+
+    type_title = department[0].upcase + department[1..]
+    filename = "cops_#{department.downcase}.md"
+    content = +"#### Department [#{type_title}](#{filename})\n\n"
+    selected_cops.each do |cop|
+      anchor = cop.cop_name.sub('/', '').downcase
+      content << "* [#{cop.cop_name}](#{filename}##{anchor})\n"
+    end
+
+    content
+  end
+  # rubocop:enable Metrics/AbcSize
+
+  def print_table_of_contents(cops)
+    path = "#{Dir.pwd}/docs/cops.md"
+    original = File.read(path)
+    content = +"<!-- START_COP_LIST -->\n"
+
+    content << table_contents(cops)
+
+    content << "\n<!-- END_COP_LIST -->"
+
+    unless original.empty?
+      content = original.sub(
+        /<!-- START_COP_LIST -->.+<!-- END_COP_LIST -->/m, content
+      )
+    end
+    File.write(path, content)
+  end
+
+  def table_contents(cops)
+    cops
+      .departments
+      .map(&:to_s)
+      .sort
+      .map { |department| table_of_content_for_department(cops, department) }
+      .compact
+      .join("\n")
+  end
+
+  def assert_docs_synchronized
+    # Do not print diff and yield whether exit code was zero
+    sh('git diff --quiet docs') do |outcome, _|
+      return if outcome
+
+      # Output diff before raising error
+      sh('GIT_PAGER=cat git diff docs')
+
+      warn('The docs directory is out of sync. ' \
+           'Run `rake generate_cops_documentation` and commit the results.')
+      exit!
+    end
+  end
+
+  def main
+    cops   = RuboCop::Cop::Cop.registry
+    config = RuboCop::ConfigLoader.load_file('config/default.yml')
+
+    YARD::Registry.load!
+    cops.departments.sort!.each do |department|
+      print_cops_of_department(cops, department, config)
+    end
+
+    print_table_of_contents(cops)
+
+    assert_docs_synchronized if ENV['CI'] == 'true'
+  ensure
+    RuboCop::ConfigLoader.default_configuration = nil
+  end
+
+  main
+end
+
+desc('Syntax check for the documentation comments')
+task documentation_syntax_check: :yard_for_generate_documentation do
+  require 'parser/ruby27'
+
+  ok = true
+  YARD::Registry.load!
+  cops = RuboCop::Cop::Cop.registry
+  cops.each do |cop|
+    examples = YARD::Registry.all(:class).find do |code_object|
+      next unless RuboCop::Cop::Badge.for(code_object.to_s) == cop.badge
+
+      break code_object.tags('example')
+    end
+
+    examples.to_a.each do |example|
+      buffer = Parser::Source::Buffer.new('<code>', 1)
+      buffer.source = example.text
+      parser = Parser::Ruby27.new(RuboCop::AST::Builder.new)
+      parser.diagnostics.all_errors_are_fatal = true
+      parser.parse(buffer)
+    rescue Parser::SyntaxError => e
+      path = example.object.file
+      puts "#{path}: Syntax Error in an example. #{e}"
+      ok = false
+    end
+  end
+  abort unless ok
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-solidus
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - piyushswain
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-07-28 00:00:00.000000000 Z
+date: 2023-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -43,6 +43,8 @@ files:
 - README.md
 - Rakefile
 - config/default.yml
+- docs/cops.md
+- docs/cops_solidus.md
 - lib/rubocop-solidus.rb
 - lib/rubocop/cop/mixin/target_solidus_version.rb
 - lib/rubocop/cop/solidus/class_eval_decorator.rb
@@ -61,10 +63,12 @@ files:
 - lib/rubocop/solidus/version.rb
 - relnotes/v0.1.2.md
 - relnotes/v0.1.3.md
+- relnotes/v0.1.4.md
 - rubocop-solidus.gemspec
 - sig/rubocop/solidus.rbs
 - tasks/changelog.rake
 - tasks/changelog.rb
+- tasks/cops_documentation.rake
 - tasks/cut_release.rake
 homepage: https://www.github.com/solidusio/rubocop-solidus
 licenses:
@@ -72,7 +76,8 @@ licenses:
 metadata:
   homepage_uri: https://www.github.com/solidusio/rubocop-solidus
   source_code_uri: https://www.github.com/solidusio/rubocop-solidus
-  changelog_uri: https://www.github.com/solidusio/rubocop-solidus
+  changelog_uri: https://www.github.com/solidusio/rubocop-solidus/blob/master/CHANGELOG.md
+  documentation_uri: https://www.github.com/solidusio/rubocop-solidus/blob/master/docs/cops.md
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -88,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.16
+rubygems_version: 3.4.18
 signing_key: 
 specification_version: 4
 summary: Automatic Solidus code style checking tool.