yard-lint 1.0.0 → 1.1.0

data/lib/yard/lint/validators/tags/tag_type_position.rb

@@ -4,8 +4,45 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # TagTypePosition validator module
-        # Detects type annotations in incorrect position (after param name instead of before)
+        # TagTypePosition validator
+        #
+        # Ensures consistent type annotation positioning in YARD documentation tags.
+        # By default, it enforces YARD standard style where the type appears after
+        # the parameter name (`@param name [Type]`), but you can configure it to
+        # enforce `type_first` style if your team prefers that convention.
+        # This validator is enabled by default.
+        #
+        # @example Good - Type after parameter name (YARD standard)
+        #   # @param name [String] the user's name
+        #   # @param age [Integer] the user's age
+        #   # @param options [Hash{Symbol => Object}] configuration options
+        #   def create_user(name, age, options = {})
+        #   end
+        #
+        # @example Bad - Type before parameter name (when using default style)
+        #   # @param [String] name the user's name
+        #   # @param [Integer] age the user's age
+        #   def create_user(name, age)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To use type_first style instead:
+        #
+        #     Tags/TagTypePosition:
+        #       EnforcedStyle: type_first
+        #
+        # @example Good - When EnforcedStyle is type_first
+        #   # @param [String] name the user's name
+        #   # @param [Integer] age the user's age
+        #   def create_user(name, age)
+        #   end
+        #
+        # To disable this validator:
+        #
+        #     Tags/TagTypePosition:
+        #       Enabled: false
+        #
         module TagTypePosition
         end
       end

data/lib/yard/lint/validators/tags/type_syntax.rb

@@ -4,8 +4,32 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # TypeSyntax validator module
-        # Validates YARD type syntax using YARD's TypesExplainer::Parser
+        # TypeSyntax validator
+        #
+        # Validates YARD type syntax using YARD's TypesExplainer::Parser. This
+        # validator ensures that type annotations can be properly parsed by YARD
+        # and follow YARD's type specification format. This validator is enabled
+        # by default.
+        #
+        # @example Bad - Invalid type syntax that YARD cannot parse
+        #   # @param data [{String, Integer}] invalid hash syntax
+        #   # @return [String]] extra closing bracket
+        #   def process(data)
+        #   end
+        #
+        # @example Good - Valid parseable YARD type syntax
+        #   # @param data [Hash{String => Integer}] valid hash syntax
+        #   # @return [String] correct bracket usage
+        #   def process(data)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/TypeSyntax:
+        #       Enabled: false
+        #
         module TypeSyntax
         end
       end

data/lib/yard/lint/validators/warnings/duplicated_parameter_name.rb

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # DuplicatedParameterName validator module
+        # DuplicatedParameterName validator
+        #
+        # Detects duplicate `@param` tags for the same parameter name. If a parameter
+        # is documented multiple times, it's unclear which documentation is correct
+        # and can confuse both readers and YARD's parser. This validator is enabled
+        # by default.
+        #
+        # @example Bad - Duplicate @param tags
+        #   # @param name [String] the name
+        #   # @param name [Symbol] oops, documented again
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Each parameter documented once
+        #   # @param name [String] the name
+        #   # @param age [Integer] the age
+        #   def process(name, age)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/DuplicatedParameterName:
+        #       Enabled: false
+        #
         module DuplicatedParameterName
         end
       end

data/lib/yard/lint/validators/warnings/invalid_directive_format.rb

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # InvalidDirectiveFormat validator module
+        # InvalidDirectiveFormat validator
+        #
+        # Detects malformed YARD directive syntax. Directives have specific format
+        # requirements (like `@!attribute [r] name` for read-only attributes), and
+        # this validator ensures those requirements are met. This validator is
+        # enabled by default.
+        #
+        # @example Bad - Malformed directive syntax
+        #   # @!attribute name missing brackets
+        #   # @!method [r] foo wrong format for method
+        #   class User
+        #   end
+        #
+        # @example Good - Correctly formatted directives
+        #   # @!attribute [r] name
+        #   # @!method foo(bar)
+        #   class User
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/InvalidDirectiveFormat:
+        #       Enabled: false
+        #
         module InvalidDirectiveFormat
         end
       end

data/lib/yard/lint/validators/warnings/invalid_tag_format.rb

@@ -5,7 +5,31 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # InvalidTagFormat validator module
+        # InvalidTagFormat validator
+        #
+        # Detects malformed YARD tag syntax. This validator checks that tags follow
+        # the correct format expected by YARD, such as proper spacing, brackets for
+        # types, and required components. This validator is enabled by default.
+        #
+        # @example Bad - Malformed tag syntax
+        #   # @param name[String] missing space before type
+        #   # @return [String the result missing closing bracket
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Correctly formatted tags
+        #   # @param name [String] the name
+        #   # @return [String] the result
+        #   def process(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/InvalidTagFormat:
+        #       Enabled: false
+        #
         module InvalidTagFormat
         end
       end

data/lib/yard/lint/validators/warnings/unknown_directive.rb

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # UnknownDirective validator module
+        # UnknownDirective validator
+        #
+        # Detects usage of unrecognized YARD directives in documentation. Directives
+        # are special YARD commands (like `@!attribute`, `@!method`) that control
+        # documentation generation. This validator flags unknown directives that
+        # could indicate errors. This validator is enabled by default.
+        #
+        # @example Bad - Unknown or misspelled directive
+        #   # @!attribute [r] name
+        #   # @!method foo
+        #   class User
+        #   end
+        #
+        # @example Good - Standard YARD directives
+        #   # @!attribute [r] name
+        #   # @!method foo
+        #   class User
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/UnknownDirective:
+        #       Enabled: false
+        #
         module UnknownDirective
         end
       end

data/lib/yard/lint/validators/warnings/unknown_parameter_name.rb

@@ -5,7 +5,29 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # UnknownParameterName validator module
+        # UnknownParameterName validator
+        #
+        # Detects `@param` tags that document parameters which don't exist in the
+        # method signature. This often occurs after refactoring when parameter names
+        # change but documentation isn't updated. This validator is enabled by default.
+        #
+        # @example Bad - @param documents non-existent parameter
+        #   # @param old_name [String] this parameter doesn't exist anymore
+        #   def process(new_name)
+        #   end
+        #
+        # @example Good - @param matches actual parameters
+        #   # @param new_name [String] the name to process
+        #   def process(new_name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/UnknownParameterName:
+        #       Enabled: false
+        #
         module UnknownParameterName
         end
       end

data/lib/yard/lint/validators/warnings/unknown_tag.rb

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # UnknownTag validator module
+        # UnknownTag validator
+        #
+        # Detects usage of unrecognized YARD tags in documentation. This validator
+        # checks against YARD's standard tag set and flags any tags that YARD
+        # doesn't recognize, which could indicate typos or unsupported tags.
+        # This validator is enabled by default.
+        #
+        # @example Bad - Misspelled or non-existent tags
+        #   # @param name [String] typo in param tag
+        #   # @returns [String] should be @return not @returns
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Standard YARD tags
+        #   # @param name [String] the name
+        #   # @return [String] the result
+        #   def process(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/UnknownTag:
+        #       Enabled: false
+        #
         module UnknownTag
         end
       end

data/lib/yard/lint/version.rb

@@ -3,6 +3,6 @@
 module Yard
   module Lint
     # @return [String] version of the YARD Lint gem
-    VERSION = '1.0.0'
+    VERSION = '1.1.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -60,6 +74,7 @@ files:
 - lib/yard/lint.rb
 - lib/yard/lint/command_cache.rb
 - lib/yard/lint/config.rb
+- lib/yard/lint/config_generator.rb
 - lib/yard/lint/config_loader.rb
 - lib/yard/lint/errors.rb
 - lib/yard/lint/formatters/progress.rb
@@ -72,6 +87,12 @@ files:
 - lib/yard/lint/runner.rb
 - lib/yard/lint/validators/base.rb
 - lib/yard/lint/validators/config.rb
+- lib/yard/lint/validators/documentation/markdown_syntax.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/config.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/messages_builder.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/parser.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/result.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/validator.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods/config.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods/parser.rb
@@ -89,6 +110,11 @@ files:
 - lib/yard/lint/validators/documentation/undocumented_objects/parser.rb
 - lib/yard/lint/validators/documentation/undocumented_objects/result.rb
 - lib/yard/lint/validators/documentation/undocumented_objects/validator.rb
+- lib/yard/lint/validators/documentation/undocumented_options.rb
+- lib/yard/lint/validators/documentation/undocumented_options/config.rb
+- lib/yard/lint/validators/documentation/undocumented_options/parser.rb
+- lib/yard/lint/validators/documentation/undocumented_options/result.rb
+- lib/yard/lint/validators/documentation/undocumented_options/validator.rb
 - lib/yard/lint/validators/semantic/abstract_methods.rb
 - lib/yard/lint/validators/semantic/abstract_methods/config.rb
 - lib/yard/lint/validators/semantic/abstract_methods/messages_builder.rb
@@ -107,6 +133,12 @@ files:
 - lib/yard/lint/validators/tags/collection_type/parser.rb
 - lib/yard/lint/validators/tags/collection_type/result.rb
 - lib/yard/lint/validators/tags/collection_type/validator.rb
+- lib/yard/lint/validators/tags/example_syntax.rb
+- lib/yard/lint/validators/tags/example_syntax/config.rb
+- lib/yard/lint/validators/tags/example_syntax/messages_builder.rb
+- lib/yard/lint/validators/tags/example_syntax/parser.rb
+- lib/yard/lint/validators/tags/example_syntax/result.rb
+- lib/yard/lint/validators/tags/example_syntax/validator.rb
 - lib/yard/lint/validators/tags/invalid_types.rb
 - lib/yard/lint/validators/tags/invalid_types/config.rb
 - lib/yard/lint/validators/tags/invalid_types/messages_builder.rb
@@ -131,6 +163,12 @@ files:
 - lib/yard/lint/validators/tags/order/parser.rb
 - lib/yard/lint/validators/tags/order/result.rb
 - lib/yard/lint/validators/tags/order/validator.rb
+- lib/yard/lint/validators/tags/redundant_param_description.rb
+- lib/yard/lint/validators/tags/redundant_param_description/config.rb
+- lib/yard/lint/validators/tags/redundant_param_description/messages_builder.rb
+- lib/yard/lint/validators/tags/redundant_param_description/parser.rb
+- lib/yard/lint/validators/tags/redundant_param_description/result.rb
+- lib/yard/lint/validators/tags/redundant_param_description/validator.rb
 - lib/yard/lint/validators/tags/tag_type_position.rb
 - lib/yard/lint/validators/tags/tag_type_position/config.rb
 - lib/yard/lint/validators/tags/tag_type_position/messages_builder.rb