Modules not checked by documentation check about cane HOT 4 CLOSED

Commenting every module seems excessive though. Would you verify at least one was documented?

module MyApp
  module SomeOtherNesting
    # My great comment
    class Blah
    end
  end
end

That said, I haven't found module documentation on namespacing modules particularly useful in understanding a system. There's no good single place for it, and it's usually pretty obvious from the name its purpose.

The mixin case could benefit:

module MyMixin
  def hello
  end
end

But I don't see a reliable way to check for it.

(Closing because there's no clear next action, but do reopen for more discussion if you like)

from cane.

That said, I haven't found module documentation on namespacing modules particularly useful in understanding a system.

In general, modules that just act as namespaces don't need documentation. I agree with that. Maybe this is just my style of development...but I'd estimate that I use modules for other things far more often than as namespaces. Besides the mixin example you gave, module Foo; extend self; end is my go-to ruby idiom for globally named singleton objects that I don't want to be instantiatable. I'd estimate that I probably only use modules as namespaces about 1/3 of the time.

So...even though I agree that documenting modules-as-namespaces is generally over kill, on my projects, I'd rather have the occasional doc comment on a module namespace in exchange for the added confidence that cane gives me that my other uses of modules have at least a minimal documentation comment.

Seems like maybe it could be a config option?

from cane.

My general rule of thumb is that I'll document modules only when they contain methods. If all they're used for is namespacing, and contain other class/module declarations only I don't think they need to be documented.

I also think if the module with-a-method occurs multiple times in the codebase (say it's being used to contain methods_and_ namespacing other classes in other source files), then I only have to document it once. Usually I would locate the documentation with the place where the module contains the methods. I know some linters and tools expect that every occurrence of the module comes with documentation, which is just silly imho.

from cane.

It would be possible to only flag modules with methods, though the existing check would need some serious modification (it currently just does a grep, would now require some parsing). I'd accept a pull request matching @dkubb's outline.

from cane.