Unexpected missing top-level module documentation comment

[fabiopelosin]

This report is relative to the Documentation cop. The output of Rubocop is the following:

$ rubocop --version
0.20.0
$ rubocop
Inspecting 38 files
..C................C...CCC.....C......

Offenses:

lib/cocoapods-core/gem_version.rb:1:1: C: Missing top-level module documentation comment.
module Pod
^^^^^^
[...]

The module Pod is commented here and the file which lead to the warning is this one.

Is this the intended behaviour?

[yujinakayama]

It's not intended but currently RuboCop cannot handle state between multiple files.

See: #323

[fabiopelosin]

Thanks for the reply. In my usage case this is unfortunate because RuboCop is used to fail the CI build with any violation so this means that this module cannot be enabled.

Although state between files is a very desirable feature, there would be another alternative to fix the
Documentation while keeping things pretty simple: allow to disable the top-level module documentation check.

[bbatsov]

Maybe such an option would make sense. Alternatively we can add constants to our namespace module check. Modules that are considered namespaces by RuboCop are not required to have documentation.

[segiddins]

Any update on this @bbatsov ?

[bbatsov]

I've been quite busy lately and I haven't tackled this yet.

[dmolesUC]

It would be nice to separate the class and module documentation checks, at least.

[segiddins]

Might it make sense to allow namespaces that have only constant children of any kind (Class, Module, Constant) to be undocumented?

[alexdowad]

Might it make sense to allow namespaces that have only constant children of any kind (Class, Module, Constant) to be undocumented?

This is very easy to implement. But do the maintainers want it? @bbatsov @jonas054

[jonas054]

Slightly expanding what we mean by namespace module. I'd be ok with that.

[alexdowad]

OK, sounds like @jonas054 likes the idea, at least a little bit. Almost all the specs for this cop will have to be adjusted. But that's OK.

[alexdowad]

Pushed a fix to my open PR. @bbatsov, if you decide that classes/modules with only constants are not "namespaces", I will delete that commit from the PR.