Layout/EmptyLines prevents separating per-file license details from documentation comments

[dmlary]

Summary

I've been given a requirement to put license comments at the top of every source file in a gem. The documentation for that gem is generated with yard. Yard parses the documentation from the top-level file declaring the top-level namespace module, but as it parses deeper files in the tree, the license comments are considered documentation for the module, overriding the true documentation.

yard has a well established solution for this, which is to separate documentation blocks with two blank lines, but the Layout/EmptyLines rule prevents this.

Detailed Example

First off the layout of the project is something like this:

lib/my_module.rb
lib/my_module/my_class.rb
# 30+ more classes in the MyModule namespace

At the top of each file is SPDX[^1] licensing comment:

# SPDX-FileCopyrightText: 2025 Company Name
# SPDX-License-Identifier: MIT

The contents of the top-level file (lib/my_module.rb) is:

# SPDX-FileCopyrightText: 2025 Company Name
# SPDX-License-Identifier: MIT

require_relative "my_module/my_class"

# This is the documentation for MyModule
# @example
#    ...
module MyModule
end

All classes and modules within the gem are declared as follows so they can easily access things in the MyModule namespace.

# SPDX-FileCopyrightText: 2025 Company Name
# SPDX-License-Identifier: MIT

module MyModule
  # This is the documentation for MyClass
  # @example using MyClass
  class MyClass
  end
end

Solutions

I see the value of Layout/EmptyLines, but this is an explicit place where additional whitespace is required to separate documentation blocks. Is there an alternate rubocop rule that could be used to allow whitespace between comment blocks, but not in code body?

[dmlary]

related issue in yard: lsegal/yard#1605