Moduledoc tag check should verify if a 'used' module adds a moduledoc tag

[Joao-M-Almeida]

Environment

• Credo version (mix credo -v): 0.8.10
• Erlang/Elixir version (elixir -v): Elixir 1.6.4 (compiled with OTP 20)
• Operating system: Mac OS

What were you trying to do?

Statically analyzing, with mix credo, a project that uses quantum to schedule jobs.

Quantum requires a scheduler module to be created that follows the following structure:

defmodule YourApp.Scheduler do
  use Quantum.Scheduler,
    otp_app: :your_app
end

This causes credo to complain that no moduledoc tag exists for this scheduler module. However, if I add a moduledoc tag the elixir compiler complains that when calling use Quantum.Scheduler I am

redefining @moduledoc attribute previously set at line 2

This is caused by the fact that the __using__ macro of Quantum.Scheduler adds a module tag by itself.

Expected outcome

No issues found by credo

Actual outcome

┃ [R] → Modules should have a @moduledoc tag.

[rrrene]

Thx for reporting! 👍 I imagine this to be a rather difficult one.

[Joao-M-Almeida]

Yes, it's definetely not trivial to identify these cases.

[tckb]

this is exactly my issue! I would want to add my own doc for my scheduler. It's credo vs inch in my case. @Joao-M-Almeida did you find any alternatives for this?

[Joao-M-Almeida]

@tckb I disabled credo for this specific issue on this file. I used:

# credo:disable-for-this-file Credo.Check.Readability.ModuleDoc

[whatyouhide]

I am not familiar with Credo enough to tell if it's possible, but if you load the compiled project in any way, you could actually call something like Code.get_docs/2 to get the documentation out of the compiled module, which takes away the AST inspection in favour of just seeing if the docs are stored in the module (works for use that adds docs as well as most cases I can think of).

[rrrene]

@whatyouhide Credo, at least for now, does not load the compiled project (it solely relies on static source code analysis).

That said, I am currently trying to re-iterate on InchEx, using the newly created EEP48 stuff from Code.fetch_docs/1. This project loads the compiled project and I could see integrating the results into Credo, if my dabbling yields any useful results.

The short-term question here is: Does it make sense to look at the uncompiled source code searching for @moduledoc tags? Maybe this check should be removed in its current form.

[Joao-M-Almeida]

Maybe this check should be removed in its current form.

I think it makes sense to keep it. It still usefull in 90% of the cases. And in the cases where it doesn't work as expected it's easy to disable.

[rrrene]

Hi, thx again for this. Unfortunately, I am closing it due to "it being obsolete" IMHO.

If you disagree, please re-open and elaborate! 👍