rubocop-yardoc 0.2.0 → 0.2.2

data/cops.adoc

@@ -0,0 +1,823 @@
+////
+  Do NOT edit this file by hand directly, as it is automatically generated.
+
+  Please make any necessary changes to the cop documentation within the source files themselves.
+////
+
+= Yardoc
+
+[#yardocclassdescription]
+== Yardoc/ClassDescription
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| No
+| -
+| -
+|===
+
+Ensures all classes have YARD documentation.
+
+Classes can be ignored by exact name, qualified name, or regexp pattern.
+
+[#examples-yardocclassdescription]
+=== Examples
+
+[source,ruby]
+----
+# bad
+
+class MyClass; end
+
+# good
+
+# A useful class.
+class MyClass; end
+----
+
+[#ignore_-___myclass__-_internal__-_mymodule__myotherclass___-yardocclassdescription]
+==== Ignore: `['MyClass', '/Internal/', 'MyModule::MyOtherClass']`
+
+[source,ruby]
+----
+# good (ignored with 'MyClass')
+
+class MyClass; end
+
+# good (ignored with /Internal/)
+
+class MyInternalClass; end
+
+module MyModule
+  # bad
+
+  class MyCustomClass; end
+
+  # good (ignored with 'MyClass')
+
+  class MyClass; end
+
+  # good (ignored with 'MyModule::MyOtherClass)
+
+  class MyOtherClass; end
+end
+----
+
+[#configurable-attributes-yardocclassdescription]
+=== Configurable attributes
+
+|===
+| Name | Default value | Configurable values
+
+| Ignore
+| `[]`
+| Array
+|===
+
+[#yardoccolumnparams]
+== Yardoc/ColumnParams
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| Always
+| -
+| -
+|===
+
+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
+
+[#examples-yardoccolumnparams]
+=== Examples
+
+[source,ruby]
+----
+# bad
+
+# @param foo [String] a foo
+# @param longer_name [Integer] a number
+# @param bar [String] A multiline, non aligned
+#   description
+def my_method(foo, longer_name, bar); end
+
+# good
+
+# @param foo         [String]  a foo
+# @param longer_name [Integer] a number
+# @param bar         [String]  A multiline, aligned
+#                              description
+def my_method(foo, longer_name, bar); end
+----
+
+[#yardocconstantdescription]
+== Yardoc/ConstantDescription
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| No
+| -
+| -
+|===
+
+Ensures all constants have YARD documentation.
+
+They can be ignored via `Ignore`, by providing the name or a regexp
+
+[#examples-yardocconstantdescription]
+=== Examples
+
+[source,ruby]
+----
+# bad
+
+MY_CONST = 10
+
+# good
+
+# That's 9 + 1
+MY_CONST = 10
+----
+
+[#ignores_-___my_const___-yardocconstantdescription]
+==== Ignores: `['MY_CONST']`
+
+[source,ruby]
+----
+# bad
+
+A_CONST = 'something'
+
+# good (ignored)
+
+MY_CONST = 10
+
+class MyClass
+  # good (ignored)
+
+  MY_CONST
+end
+----
+
+[#ignores_-____my_const___-yardocconstantdescription]
+==== Ignores: `['/^MY_CONST/']`
+
+[source,ruby]
+----
+# bad
+
+A_CONST = 'something'
+
+# good (ignored)
+
+MY_CONST = 10
+
+class MyClass
+  # bad
+
+  MY_CONST
+end
+----
+
+[#ignores_-___myclass__my_const___-yardocconstantdescription]
+==== Ignores: `['MyClass::MY_CONST']`
+
+[source,ruby]
+----
+# bad
+
+A_CONST = 'something'
+
+# bad
+
+MY_CONST = 10
+
+class MyClass
+  # good (ignored)
+
+  MY_CONST
+end
+----
+
+[#configurable-attributes-yardocconstantdescription]
+=== Configurable attributes
+
+|===
+| Name | Default value | Configurable values
+
+| Ignore
+| `[]`
+| Array
+|===
+
+[#yardocmethoddescription]
+== Yardoc/MethodDescription
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| No
+| -
+| -
+|===
+
+Ensures all 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`.
+
+[#examples-yardocmethoddescription]
+=== Examples
+
+[#documentprivate_-_true_-_default_-yardocmethoddescription]
+==== DocumentPrivate: `true` (default)
+
+[source,ruby]
+----
+# bad
+
+def my_method; end
+
+# bad
+
+# @param name [String] The name
+def some_method(name); end
+
+# good
+
+# Does something useful.
+def my_other_method; end
+
+private
+
+# good
+
+# Does something useful.
+# def my_other_other_method; end
+----
+
+[#documentprivate_-_true_-yardocmethoddescription]
+==== DocumentPrivate: `true`
+
+[source,ruby]
+----
+private
+
+# good
+
+def secret; end
+----
+
+[#ignore_-___a_method___-yardocmethoddescription]
+==== Ignore: `['a_method']`
+
+[source,ruby]
+----
+# bad
+
+def something; end
+
+# good (ignored)
+
+def a_method; end
+
+class MyClass
+  # good (ignored)
+
+  def a_method; end
+end
+----
+
+[#ignore_-____a_m___-yardocmethoddescription]
+==== Ignore: `['/^a_m/']`
+
+[source,ruby]
+----
+# bad
+
+def something; end
+
+# good (ignored)
+
+def a_method; end
+
+class MyClass
+  # good (ignored)
+
+  def a_method; end
+end
+----
+
+[#ignore_-___myclass__a_method___-yardocmethoddescription]
+==== Ignore: `['MyClass::a_method']`
+
+[source,ruby]
+----
+# bad
+
+def something; end
+
+# bad
+
+def a_method; end
+
+class MyClass
+  # good (ignored)
+
+  def a_method; end
+end
+----
+
+[#configurable-attributes-yardocmethoddescription]
+=== Configurable attributes
+
+|===
+| Name | Default value | Configurable values
+
+| DocumentPrivate
+| `true`
+| Boolean
+
+| Ignore
+| `[]`
+| Array
+|===
+
+[#yardocmoduledescription]
+== Yardoc/ModuleDescription
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| No
+| -
+| -
+|===
+
+Ensures all modules have YARD documentation.
+
+Modules can be ignored by exact name, qualified name, or regexp pattern.
+
+[#examples-yardocmoduledescription]
+=== Examples
+
+[source,ruby]
+----
+# bad
+
+module MyModule; end
+
+# good
+
+# A useful module.
+module MyModule; end
+----
+
+[#ignore_-___mymodule__-_internal__-_mymodule__mysubmodule___-yardocmoduledescription]
+==== Ignore: `['MyModule', '/Internal/', 'MyModule::MySubModule']`
+
+[source,ruby]
+----
+# good (ignored with '/Internal/')
+
+module MyInternalModule; end
+
+# good (ignored with 'MyModule')
+
+module MyModule; end
+
+# bad
+
+module MyOtherModule
+  # good (ignored with 'MyModule::MySubModule')
+
+  module MySubModule; end
+
+  # good (ignored with 'MyModule')
+
+  module MyModule; end
+end
+----
+
+[#configurable-attributes-yardocmoduledescription]
+=== Configurable attributes
+
+|===
+| Name | Default value | Configurable values
+
+| Ignore
+| `[]`
+| Array
+|===
+
+[#yardocparamdescriptioncasing]
+== Yardoc/ParamDescriptionCasing
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| Always
+| -
+| -
+|===
+
+Ensure every "param" and "return" tag starts with an uppercased letter
+
+It ignores description starting with non latin characters
+
+[#examples-yardocparamdescriptioncasing]
+=== Examples
+
+[source,ruby]
+----
+# 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
+----
+
+[#yardocparamdocumentation]
+== Yardoc/ParamDocumentation
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| No
+| -
+| -
+|===
+
+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.
+
+[#examples-yardocparamdocumentation]
+=== Examples
+
+[#requiredescription_-_true_-_default_-yardocparamdocumentation]
+==== RequireDescription: `true` (default)
+
+[source,ruby]
+----
+# bad
+
+# @param name [String]
+def greet(name); end
+
+# good
+
+# @param name [String] the name to greet
+def greet(name); end
+----
+
+[#requiredescription_-_false_-yardocparamdocumentation]
+==== RequireDescription: `false`
+
+[source,ruby]
+----
+# good
+
+# @param name [String]
+def greet(name); end
+----
+
+[#configurable-attributes-yardocparamdocumentation]
+=== Configurable attributes
+
+|===
+| Name | Default value | Configurable values
+
+| RequireDescription
+| `true`
+| Boolean
+|===
+
+[#yardocseparatetagsblocks]
+== Yardoc/SeparateTagsBlocks
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| Always
+| -
+| -
+|===
+
+Ensures there are blank comment lines between blocks of tags in
+documentation comments.
+
+[#examples-yardocseparatetagsblocks]
+=== Examples
+
+[source,ruby]
+----
+# bad
+
+# Title
+# @param x [Integer] desc
+# @param y [Integer] desc
+# @return [void]
+def my_method(x, y); end
+
+# good
+
+# Title
+#
+# @param x [Integer] desc
+# @param y [Integer] desc
+#
+# @return [void]
+def my_method(x, y); end
+----
+
+[#yardocsupportedtags]
+== Yardoc/SupportedTags
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| No
+| -
+| -
+|===
+
+Ensures only supported YARD tags are used.
+
+The built-in supported tags follow the official YARD tag list.
+
+Additional tags can be whitelisted via `AdditionalTags` if they are
+not properly registered in Yardoc
+See Adding Custom Tags: https://rubydoc.info/gems/yard/file/docs/TagsArch.md#Adding_Custom_Tags
+
+Meta tags are not supported (`@!<tag>`, used when metaprogramming).
+
+[#examples-yardocsupportedtags]
+=== Examples
+
+[source,ruby]
+----
+# good
+
+# @param name [String] a name
+# @return [void]
+def foo(name); end
+
+# bad
+
+# @unknown_tag some value
+def foo; end
+----
+
+[#additionaltags_-___custom_tag___-yardocsupportedtags]
+==== AdditionalTags: `['custom_tag']`
+
+[source,ruby]
+----
+# good
+
+# @custom_tag some value
+def foo; end
+----
+
+[#configurable-attributes-yardocsupportedtags]
+=== Configurable attributes
+
+|===
+| Name | Default value | Configurable values
+
+| AdditionalTags
+| `[]`
+| Array
+|===
+
+[#yardoctagorder]
+== Yardoc/TagOrder
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| No
+| -
+| -
+|===
+
+Ensures YARD tags appear in the configured order.
+
+Override with the `Order` config option.
+
+[#examples-yardoctagorder]
+=== Examples
+
+[source,ruby]
+----
+# bad
+
+# @return [void]
+# @param name [String] a name
+def foo(name); end
+
+# good
+
+# @param name [String] a name
+# @return [void]
+def foo(name); end
+----
+
+[#order_-___return__-_param___-yardoctagorder]
+==== Order: `['return', 'param']`
+
+[source,ruby]
+----
+# bad
+
+# @param name [String] a name
+# @return [void]
+def foo(name); end
+
+# good
+
+# @return [void]
+# @param name [String] a name
+def foo(name); end
+----
+
+[#configurable-attributes-yardoctagorder]
+=== Configurable attributes
+
+|===
+| Name | Default value | Configurable values
+
+| Order
+| `deprecated`, `param`, `return`, `yieldparam`, `yieldreturn`, `option`, `raise`, `see`, `since`, `note`, `example`
+| Array
+|===
+
+[#yardoctypesformat]
+== Yardoc/TypesFormat
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| Always
+| -
+| -
+|===
+
+Ensures all types are separated by a space
+
+[#examples-yardoctypesformat]
+=== Examples
+
+[source,ruby]
+----
+# bad
+
+# @param [String,nil]
+def greet(name); end
+
+# good
+
+# @param name [String, nil]
+def greet(name); end
+----
+
+[#yardocvalidtypes]
+== Yardoc/ValidTypes
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| Always
+| -
+| -
+|===
+
+Ensures all types are parseable by YARD.
+
+[#examples-yardocvalidtypes]
+=== Examples
+
+[source,ruby]
+----
+# bad
+
+# @param name [.method, Array[String]] the name to greet
+def greet(name); end
+
+# good
+
+# @param [String, List(item, item2), Array<String>, Hash{String, Integer}, ClassName, #method, nil, true]
+def greet(name); end
+----
+
+[#yardocyielddocumentation]
+== Yardoc/YieldDocumentation
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Enabled
+| Yes
+| No
+| -
+| -
+|===
+
+Ensures methods that yield a block document it with @yield.
+
+Also checks for @yieldparam when the yield passes arguments,
+and @yieldreturn when the yield's return value is used.
+
+[#examples-yardocyielddocumentation]
+=== Examples
+
+[#requireparamdocumentation_-_true_-_default_-yardocyielddocumentation]
+==== RequireParamDocumentation: `true` (default)
+
+[source,ruby]
+----
+# bad
+
+def each
+  yield item
+end
+
+# good
+
+# @yield [item] iterates over items
+# @yieldparam item [Object] the current item
+def each
+  yield item
+end
+----
+
+[#requireparamdocumentation_-_false_-yardocyielddocumentation]
+==== RequireParamDocumentation: `false`
+
+[source,ruby]
+----
+# bad (no yield documentation)
+
+def each
+  yield item
+end
+
+# good (ignored)
+
+# @yield [item] iterates over items
+def each
+  yield item
+end
+----
+
+[#configurable-attributes-yardocyielddocumentation]
+=== Configurable attributes
+
+|===
+| Name | Default value | Configurable values
+
+| RequireParamDocumentation
+| `true`
+| Boolean
+|===