Module: Yard::Lint::Validators::Documentation::OrphanedDocComment

Defined in:

lib/yard/lint/validators/documentation/orphaned_doc_comment.rb,
lib/yard/lint/validators/documentation/orphaned_doc_comment/config.rb,
lib/yard/lint/validators/documentation/orphaned_doc_comment/parser.rb,
lib/yard/lint/validators/documentation/orphaned_doc_comment/result.rb,
lib/yard/lint/validators/documentation/orphaned_doc_comment/validator.rb,
lib/yard/lint/validators/documentation/orphaned_doc_comment/messages_builder.rb

Overview

Note:

This validator is complementary to ‘Documentation/BlankLineBeforeDefinition`, which catches doc blocks separated from a `def` by blank lines. `OrphanedDocComment` catches doc blocks that lead to non-definition code entirely.

OrphanedDocComment validator

Detects YARD documentation comment blocks that contain tags (‘@param`, `@return`, etc.) but are not attached to any documentable Ruby construct. YARD silently drops these comments - they never appear in the registry and the documentation is permanently lost.

This happens when a YARD-tagged comment is immediately followed by a non-documentable statement (variable assignment, ‘require`, `include`, etc.) or sits at the end of a file.

## Configuration

To disable this validator:

Documentation/OrphanedDocComment:
  Enabled: false

Examples:

Bad - comment before variable assignment

# @param name [String] the name
# @return [void]
MY_CONSTANT = "value"

Bad - comment before require

# @param name [String] the name
require "some_gem"

Bad - comment at end of file

# @param name [String] the name
# @return [void]
# (EOF)

Good - comment before def

# @param name [String] the name
# @return [void]
def process(name)
end

Defined Under Namespace

Classes: Config, MessagesBuilder, Parser, Result, Validator