WIP: add doc to cops

lib/rubocop/cop/discourse/plugins/call_requires_plugin.rb

@@ -4,6 +4,23 @@ module RuboCop
   module Cop
     module Discourse
       module Plugins
+        # Plugin controllers must call `requires_plugin` to prevent routes from
+        # being accessible when the plugin is disabled.
+        #
+        # @example
+        #   # bad
+        #   class MyController
+        #     def my_action
+        #     end
+        #   end
+        #
+        #   # good
+        #   class MyController
+        #     requires_plugin PLUGIN_NAME
+        #     def my_action
+        #     end
+        #   end
+        #
         class CallRequiresPlugin < Base
           MSG =
             "Use `requires_plugin` in controllers to prevent routes from being accessible when plugin is disabled."

lib/rubocop/cop/discourse/plugins/check_plugin_is_enabled.rb

@@ -4,6 +4,25 @@ module RuboCop
   module Cop
     module Discourse
       module Plugins
+        # When adding methods to an existing class, add a guard clause to check
+        # whether the plugin is enabled.
+        #
+        # @example
+        #   # bad
+        #   class ::Topic
+        #     def new_method
+        #       do_something
+        #     end
+        #   end
+        #
+        #   # good
+        #   class ::Topic
+        #     def new_method
+        #       return unless SiteSetting.my_plugin_enabled?
+        #       do_something
+        #     end
+        #   end
+        #
         class CheckPluginIsEnabled < Base
           MSG = "Check the plugin is enabled."
 

lib/rubocop/cop/discourse/plugins/discourse_event.rb

@@ -4,6 +4,15 @@ module RuboCop
   module Cop
     module Discourse
       module Plugins
+        # Using `DiscourseEvent.on` leaves the handler enabled when the plugin is disabled.
+        #
+        # @example
+        #   # bad
+        #   DiscourseEvent.on(:event) { do_something }
+        #
+        #   # good
+        #   on(:event) { do_something }
+        #
         class DiscourseEvent < Base
           MSG =
             "Use `on` instead of `DiscourseEvent.on` as the latter will listen to events even if the plugin is disabled."

lib/rubocop/cop/discourse/plugins/namespace_constants.rb

@@ -4,6 +4,17 @@ module RuboCop
   module Cop
     module Discourse
       module Plugins
+        # Constants must be defined inside the plugin namespace (module or class).
+        #
+        # @example
+        #   # bad
+        #   MY_CONSTANT = :value
+        #
+        #   # good
+        #   module MyPlugin
+        #     MY_CONSTANT = :value
+        #   end
+        #
         class NamespaceConstants < Base
           MSG = "Don’t define constants outside a class or a module."
 

lib/rubocop/cop/discourse/plugins/namespace_methods.rb

@@ -4,6 +4,19 @@ module RuboCop
   module Cop
     module Discourse
       module Plugins
+        # Methods must be defined inside the plugin namespace (module or class).
+        #
+        # @example
+        #   # bad
+        #   def my_method
+        #   end
+        #
+        #   # good
+        #   module MyPlugin
+        #     def my_method
+        #     end
+        #   end
+        #
         class NamespaceMethods < Base
           MSG = "Don’t define methods outside a class or a module."
 

lib/rubocop/cop/discourse/plugins/no_monkey_patching.rb

@@ -4,6 +4,47 @@ module RuboCop
   module Cop
     module Discourse
       module Plugins
+        # Don’t monkey-patch classes directly in `plugin.rb`. Instead, define
+        # additional methods in a dedicated mixin (an ActiveSupport concern for
+        # example) and use `prepend` (this allows calling `super` from the mixin).
+        #
+        # If you’re just adding new methods to an existing serializer, then use
+        # `add_to_serializer` instead.
+        #
+        # @example generic monkey-patching
+        #   # bad
+        #   ::Topic.class_eval do
+        #     has_many :new_items
+        #
+        #     def new_method
+        #     end
+        #   end
+        #
+        #   # good
+        #   module MyPlugin::TopicExtension
+        #     extend ActiveSupport::Concern
+        #
+        #     prepended do
+        #       has_many :new_items
+        #     end
+        #
+        #     def new_method
+        #     end
+        #   end
+        #
+        #   ::Topic.prepend(MyPlugin::TopicExtension)
+        #
+        # @example for serializers
+        #   # bad
+        #   UserSerializer.class_eval do
+        #     def new_method
+        #       do_processing
+        #     end
+        #   end
+        #
+        #   # good
+        #   add_to_serializer(:user, :new_method) { do_processing }
+        #
         class NoMonkeyPatching < Base
           MSG =
             "Don’t reopen existing classes. Instead, create a mixin and use `prepend`."

lib/rubocop/cop/discourse/plugins/use_require_relative.rb

@@ -4,6 +4,15 @@ module RuboCop
   module Cop
     module Discourse
       module Plugins
+        # Use `require_relative` to load dependencies.
+        #
+        # @example
+        #   # bad
+        #   load File.expand_path("../lib/my_file.rb", __FILE__)
+        #
+        #   # good
+        #   require_relative "lib/my_file"
+        #
         class UseRequireRelative < Base
           MSG = "Use `require_relative` instead of `load`."
           RESTRICT_ON_SEND = [:load].freeze