Module: Yard::Lint::Validators::Documentation::DuplicateNamespaceComment

Defined in:: lib/yard/lint/validators/documentation/duplicate_namespace_comment.rb,
lib/yard/lint/validators/documentation/duplicate_namespace_comment/config.rb,
lib/yard/lint/validators/documentation/duplicate_namespace_comment/parser.rb,
lib/yard/lint/validators/documentation/duplicate_namespace_comment/result.rb,
lib/yard/lint/validators/documentation/duplicate_namespace_comment/validator.rb,
lib/yard/lint/validators/documentation/duplicate_namespace_comment/messages_builder.rb

Overview

DuplicateNamespaceComment validator

Detects namespaces (modules and classes) that carry a YARD documentation comment in more than one file. When a namespace is reopened across several files, YARD merges every reopening into a single object and keeps only one docstring - the last documented reopening wins and all the other comments are silently discarded, with no warning. This is a common accident for shared namespaces (e.g. Users or Users::Operations) that are spread across many files. It is not a concern for a leaf object such as Users::Operations::Create which is normally defined in a single file and can only be documented once.

The validator reports one offense per namespace that is documented in two or more files, listing every documented location so the duplicates can be consolidated into a single canonical spot.

Configuration

To disable this validator:

Documentation/DuplicateNamespaceComment:
  Enabled: false

Examples:

Bad - the same namespace documented in two files

# a.rb
# Handles user operations
module Users; end

# b.rb
# User-related helpers   # &lt;- silently discarded by YARD
module Users; end

Good - document the namespace in exactly one place

# a.rb
# Handles user operations
module Users; end

# b.rb
module Users; end        # &lt;- reopened without a comment

Defined Under Namespace

Classes: Config, MessagesBuilder, Parser, Result, Validator