rubocop-yardoc 0.1.0

data/lib/rubocop/cop/yardoc/class_description.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures all classes have YARD documentation.
+      #
+      # Classes can be ignored by exact name, qualified name, or regexp pattern.
+      #
+      # @example
+      #   # bad
+      #   class MyClass
+      #   end
+      #
+      #   # good
+      #   # A useful class.
+      #   class MyClass
+      #   end
+      #
+      # @example Ignore: ['MyClass', '/Internal/', 'MyModule::MyClass']
+      #   # good (ignored)
+      #   class MyClass; end
+      #
+      #   # good (ignored)
+      #   class MyInternalClass; end
+      #
+      #   module MyModule
+      #     # good (ignored)
+      #     class MyCustomClass; end
+      #     # good (ignored)
+      #     class MyClass; end
+      #   end
+      class ClassDescription < Base
+        include NodeNameHelp
+
+        MSG = 'Missing YARD documentation for class `%<name>s`.'
+
+        # Executed for each class definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_class(node)
+          full_name = fully_qualified_name(node) # MyClass::my_method
+          name = full_name.split('::').last # my_method
+          return if ignored?(full_name, ignore_list) || ignored?(name, ignore_list)
+          return if documented?(node)
+
+          add_offense(node, message: format(MSG, name: full_name))
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc/column_params.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures @param tags are correctly formatted and aligned.
+      #
+      # Rules enforced:
+      # - Type must appear in square brackets directly after the param name
+      # - All @param type columns must be aligned
+      # - All @param description columns must be aligned
+      # - Multiline descriptions must align with the first description character
+      #
+      # @example
+      #   # bad
+      #   # @param foo [String] a foo
+      #   # @param longer_name [Integer] a number
+      #   # @param bar [String] A multiline, non aligned
+      #   #   description
+      #
+      #   # good
+      #   # @param foo         [String]  a foo
+      #   # @param longer_name [Integer] a number
+      #   # @param bar         [String]  A multiline, aligned
+      #   #                              description
+      class ColumnParams < Base
+        extend AutoCorrector
+        include ParamHelp
+        include YardHelp
+
+        MSG_TYPE_MISSING = '@param `%<name>s` must have a type in [brackets].'
+        MSG_ALIGNMENT    = '@param tags must have aligned types and descriptions.'
+        MSG_MULTILINE    = 'Multiline @param description must align with the first description character.'
+
+        # Executed for every method definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_def(node)
+          param_lines = extract_param_lines(node)
+          return if param_lines.empty?
+
+          check_types_present(node, param_lines) unless config.for_cop('Yardoc/ParamDocumentation')['Enabled']
+          check_alignment(param_lines)
+          check_multiline_alignment(node, param_lines)
+        end
+
+        alias on_defs on_def
+
+        private
+
+        # Parses raw comment lines into structured param line data.
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        #
+        # @return [Array<Hash>]
+        def extract_param_lines(node) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          param_tags_and_positions(node).filter_map do |param|
+            stripped = param[:source].sub(/^#\s*/, '')
+
+            match = stripped.match(/^@param\s+(\S+)(\s+\[([^\]]*)\])?(\s+(.*))?$/)
+            next unless match
+
+            # Use the match values as the Yardoc tag data may be formatted differently
+            {
+              range:    param[:range],
+              line:     param[:source],
+              comment:  param[:comment],
+              yard_tag: param[:yard_tag],
+              name:     match[1],
+              type:     match[3],
+              text:     match[5] || '',
+              type_col: param[:source].index('['),
+              desc_col: match[5] ? param[:source].index(match[5]) : nil,
+            }
+          end
+        end
+
+        # Checks that every param has a type
+        #
+        # @param node        [RuboCop::AST::Node] The AST node
+        # @param param_lines [Array<Hash>]        Hashes containing informations about the parameters
+        def check_types_present(node, param_lines)
+          param_lines.each do |pl|
+            next unless pl[:type].nil?
+
+            add_offense(node, message: format(MSG_TYPE_MISSING, name: pl[:name]))
+          end
+        end
+
+        # Checks for the alignment of comments types and descriptions
+        #
+        # @param param_lines [Array<Hash>] Hashes containing informations about the parameters
+        def check_alignment(param_lines) # rubocop:disable Metrics/MethodLength
+          return if param_lines.count <= 1
+
+          longest_type_pos, longest_text_pos = param_tag_bits_positions(param_lines)
+
+          param_lines.each do |line|
+            expected = "# @param #{line[:name]}".ljust(longest_type_pos, ' ') +
+                       "[#{line[:type]}]"
+            expected = expected.ljust(longest_text_pos, ' ') + line[:text]
+
+            next if line[:line] == expected
+
+            add_offense(line[:range], message: MSG_ALIGNMENT) do |corrector|
+              corrector.replace(line[:comment], expected)
+            end
+          end
+        end
+
+        # Finds the ideal starting position for all types and descriptions
+        #
+        # @param param_lines [Array<Hash>] Hashes containing informations about the parameters
+        #
+        # @return [Array<Integer>] Types position, descriptions position
+        def param_tag_bits_positions(param_lines) # rubocop:disable Metrics/AbcSize
+          longest_type_pos = param_lines.max_by { |l| l[:name].length }[:name].length + 10
+          longest_text_pos = param_lines.max_by { |l| l[:name].length + (l[:type]&.length || 0) }
+          # Type may not have been defined
+          longest_text_pos = longest_text_pos[:type] ? longest_text_pos[:type].length + longest_type_pos + 3 : 0
+
+          [longest_type_pos, longest_text_pos]
+        end
+
+        # Checks for the alignment of multiline comments
+        #
+        # @param node        [RuboCop::AST::Node] The AST node
+        # @param param_lines [Array<Hash>]        Hashes containing informations about the parameters
+        def check_multiline_alignment(node, param_lines) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+          longest_text_pos = param_tag_bits_positions(param_lines)[1]
+
+          comments = processed_source.ast_with_comments[node]
+          comments.each_with_index do |comment, index|
+            next unless comment.text.match?(/^# @param /)
+
+            # Search for continuations
+            comments[(index + 1)..].each do |next_comment|
+              break unless next_comment.text.match?(/^#\s{3,}/)
+
+              text = next_comment.text.sub(/#\s+/, '')
+              expected = "##{' ' * (longest_text_pos - 1)}#{text}"
+
+              next if next_comment.text == expected
+
+              add_offense(next_comment, message: MSG_MULTILINE) do |corrector|
+                corrector.replace(next_comment, expected)
+              end
+            end
+          end
+        end
+
+        # Returns lines immediately following a param line that are
+        # plain comment continuations (not new tags).
+        #
+        # @param comments   [Array<String>] All comment lines
+        # @param param_line [String]        The @param line to find continuations for
+        #
+        # @return [Array<String>] Continuation lines
+        def following_continuation_lines(comments, param_line)
+          index = comments.index(param_line)
+          return [] if index.nil?
+
+          result = []
+          comments[(index + 1)..].each do |line|
+            break unless line.match?(/^#\s{3,}/)
+
+            result << line
+          end
+          result
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc/constant_description.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures all constants have YARD documentation.
+      #
+      # They can be ignored via `Ignore`, by providing the name or a regexp
+      #
+      # @example
+      #   # bad
+      #   MY_CONST = 10
+      #
+      #   # good
+      #   # That's 9+1
+      #   MY_CONST = 10
+      #
+      # @example Ignores: ['MY_CONST']
+      #   # bad
+      #   A_CONST = 'something'
+      #
+      #   # good (ignored)
+      #   MY_CONST = 10
+      #
+      #   class MyClass
+      #     # good (ignored)
+      #     MY_CONST
+      #   end
+      #
+      # @example Ignores: [/^MY_CONST/]
+      #   # bad
+      #   A_CONST = 'something'
+      #
+      #   # good (ignored)
+      #   MY_CONST = 10
+      #
+      #   class MyClass
+      #     # bad
+      #     MY_CONST
+      #   end
+      #
+      # @example Ignores: ['MyClass::MY_CONST']
+      #   # bad
+      #   A_CONST = 'something'
+      #
+      #   # bad
+      #   MY_CONST = 10
+      #
+      #   class MyClass
+      #     # good (ignored)
+      #     MY_CONST
+      #   end
+      class ConstantDescription < Base
+        include NodeNameHelp
+
+        MSG = 'Missing YARD documentation for constant `%<name>s`.'
+
+        # Executed for each constant definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_casgn(node)
+          _scope, name, = node.children
+          name = name.to_s
+          full_name = fully_qualified_name(node)
+          full_name += "::#{name}"
+          return if ignored?(name, ignore_list) || ignored?(full_name, ignore_list)
+          return if documented?(node)
+
+          add_offense(node, message: format(MSG, name: name))
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc/method_description.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures all public methods have a description.
+      #
+      # This does not ensure parameters and other documentation, only the description
+      #
+      # Private/protected methods are skipped unless `DocumentPrivate: true`.
+      # Methods can be ignored via `Ignore`.
+      #
+      # @example
+      #   # bad
+      #   def my_method; end
+      #
+      #   # good
+      #   # Does something useful.
+      #   def my_method; end
+      #
+      # @example DocumentPrivate: true
+      #   # bad
+      #   private
+      #
+      #   def secret; end
+      #
+      # @example Ignore: [a_method]
+      #   # bad
+      #   def something; end
+      #
+      #   # good (ignored)
+      #   def a_method; end
+      #
+      #   class MyClass
+      #     # good (ignored)
+      #     def a_method; end
+      #   end
+      #
+      # @example Ignore: [/^a_m/]
+      #   # bad
+      #   def something; end
+      #
+      #   # good (ignored)
+      #   def a_method; end
+      #
+      #   class MyClass
+      #     # good (ignored)
+      #     def a_method; end
+      #   end
+      #
+      # @example Ignore: [MyClass::a_method]
+      #   # bad
+      #   def something; end
+      #
+      #   # bad
+      #   def a_method; end
+      #
+      #   class MyClass
+      #     # good (ignored)
+      #     def a_method; end
+      #   end
+      class MethodDescription < Base
+        include VisibilityHelp
+        include NodeNameHelp
+
+        MSG = 'Missing YARD documentation for method `%<name>s`.'
+
+        # Executed for each method definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_def(node)
+          name = node.method_name.to_s
+          full_name = fully_qualified_name(node)
+          full_name += "::#{name}"
+          return if ignored?(name, ignore_list) || ignored?(full_name, ignore_list)
+          return if skip_private? && node_visibility(node) == :private
+          return if documented?(node)
+
+          add_offense(node, message: format(MSG, name: name))
+        end
+
+        alias on_defs on_def
+
+        private
+
+        # Whether to skip documentation on private methods
+        def skip_private?
+          !cop_config.fetch('DocumentPrivate', false)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc/module_description.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures all modules have YARD documentation.
+      #
+      # Modules can be ignored by exact name, qualified name, or regexp pattern.
+      #
+      # @example
+      #   # bad
+      #   module MyModule
+      #   end
+      #
+      #   # good
+      #   # A useful module.
+      #   module MyModule
+      #   end
+      #
+      # @example Ignore: ['MyModule', '/Internal/', 'MyModule::MySubModule']
+      #   # good (ignored)
+      #   module MyModule; end
+      #
+      #   # good (ignored)
+      #   module MyInternalModule; end
+      #
+      #   module MyModule
+      #     # good (ignored)
+      #     module MySubModule; end
+      #     # good (ignored)
+      #     module MyModule; end
+      #   end
+      class ModuleDescription < Base
+        include NodeNameHelp
+
+        MSG = 'Missing YARD documentation for module `%<name>s`.'
+
+        # Executed for each module definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_module(node)
+          full_name = fully_qualified_name(node)
+          name = full_name.split('::').last
+          return if ignored?(name, ignore_list) || ignored?(full_name, ignore_list)
+          return if documented?(node)
+
+          add_offense(node, message: format(MSG, name: full_name))
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc/param_description_casing.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensure every "param" and "return" tag starts with an uppercased letter
+      #
+      # It ignores description starting with non latin characters
+      #
+      # @example
+      #   # bad
+      #   # @param x [Integer] desc
+      #   # @return [void] desc
+      #   def my_method(x); end
+      #
+      #   # good
+      #   # @param x [Integer] Desc
+      #   # @return [void] Desc
+      #   def my_method(x); end
+      #
+      class ParamDescriptionCasing < Base
+        extend AutoCorrector
+
+        # Represents a comment entry (it may be a multi-line comment)
+        #
+        # @return [Struct] With :comment, :text, :tag, :line, :blank?
+        CommentEntry = Struct.new(:comment, :text, :tag, :line, :blank, keyword_init: true) do
+          # Whether the comment is empty
+          #
+          # @return [Boolean]
+          def blank?
+            blank
+          end
+        end
+
+        MSG = 'First letter of a @param or @return tag should be in uppercase'
+
+        # Matches a "param" tag line
+        PARAM_REGEXP = /(?<definition>\A#\s+@param\s+[^\[]+(?:\s+\[[^\]]+\])?\s+)(?<desc>[a-z].*)/
+        # Matches a "return" tag line
+        RETURN_REGEXP = /(?<definition>\A#\s+@return\s+(?:\[[^\]]+\])?\s+)(?<desc>[a-z].*)/
+
+        # Executed for each method definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_def(node)
+          return unless documented? node
+
+          processed_source.comments
+                          .each do |line|
+                            match = line.text.match(PARAM_REGEXP) || line.text.match(RETURN_REGEXP)
+                            next unless match
+
+                            range = offense_range(line, match[:definition])
+                            add_offense(range) do |corrector|
+                              corrector.replace(range, match[:desc][0].upcase)
+                            end
+                          end
+        end
+
+        alias on_defs on_def
+
+        private
+
+        # Returns the position of the first character of the description in the line
+        #
+        # @param comment    [Parser::Source::Comment] Offending comment
+        # @param param_lead [String]                  Part of the comment to definition, e.g.: "# @param x [Integer]"
+        #
+        # @return [Parser::Source::Range]
+        def offense_range(comment, param_lead)
+          comment_range = comment.loc.expression
+          at_pos        = param_lead.length
+
+          Parser::Source::Range.new processed_source.buffer,
+                                    comment_range.begin_pos + at_pos,
+                                    comment_range.begin_pos + at_pos + 1
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc/param_documentation.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures all method parameters are documented with @param tags.
+      #
+      # By default, each @param must include a name, type, and description.
+      # Set `RequireDescription: false` to only require name and type.
+      #
+      # @example RequireDescription: true (default)
+      #   # bad
+      #   # @param name [String]
+      #   def greet(name); end
+      #
+      #   # good
+      #   # @param name [String] the name to greet
+      #   def greet(name); end
+      #
+      # @example RequireDescription: false
+      #   # good
+      #   # @param name [String]
+      #   def greet(name); end
+      class ParamDocumentation < Base
+        include ParamHelp
+        include YardHelp
+
+        MSG_MISSING        = 'Missing @param documentation for `%<names>s`.'
+        MSG_NO_TYPE        = '@param `%<name>s` is missing a type (e.g. [String]).'
+        MSG_NO_DESCRIPTION = '@param `%<name>s` is missing a description.'
+
+        # Executed for every method definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_def(node) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+          return unless documented?(node)
+
+          def_params = method_params(node)
+          param_tags = param_tags_and_positions(node)
+
+          undocumented_params = []
+
+          def_params.each do |param_name|
+            tag = param_tags.find { |t| t[:name] == param_name.to_s }
+
+            # Undocumented params are a one-offense error as we cannot add multiple offenses on the same node
+            # FIXME: add a separate offense for every undocumented param with the argument position in the
+            #        method definition.
+            if tag.nil?
+              undocumented_params << param_name
+              next
+            end
+
+            if tag[:yard_tag].types.nil? || tag[:yard_tag].types.empty?
+              add_offense(tag[:range], message: format(MSG_NO_TYPE, name: param_name))
+            end
+
+            if require_description? && (tag[:yard_tag].text.nil? || tag[:yard_tag].text.strip.empty?)
+              add_offense(tag[:range], message: format(MSG_NO_DESCRIPTION, name: param_name))
+            end
+          end
+
+          return if undocumented_params.empty?
+
+          add_offense(node, message: format(MSG_MISSING, names: undocumented_params.join('`, `')))
+        end
+
+        alias on_defs on_def
+
+        private
+
+        # Whether the description is needed for parameters
+        def require_description?
+          cop_config.fetch('RequireDescription', true)
+        end
+
+        # Extracts method parameters for given node
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def method_params(node)
+          ignored_argument_types = [:blockarg, :shadowarg, :forward_arg]
+
+          args_node = node.arguments
+          args_node.children.filter_map do |arg|
+            next if ignored_argument_types.include?(arg.type)
+
+            arg.children.first
+          end
+        end
+      end
+    end
+  end
+end