How to remove waring "Modules should have a @moduledoc tag" - mix credo -a

Questions / Help
1

I am using mix credo -a to check code readably. But I am getting multiple message as “Modules should have a @moduledoc tag.” I am not sure how to suppress/remove this.
Thanks in advance for any kind of help.

2

Sometimes when you are not sure about how to solve an issue, you can use mix credo explain, and it will tell you something about the suggestion and how to resolve it.

The simplest way though to solve your issue at hand is, to simply document the modules that have this issue: @moduledoc

1 Like
3

Thanks @NobbZ for your help. I’ll try this and hope this will solve my issue.

1 Like
4

Or you could just document your modules :wink:

4 Likes
5

Yes, that seems to be the actual reason of this warning. :slight_smile: Thanks.

6

That command alone will not solve anything, its just that it might give you some more in depth explanation of an issue.

To solve the actual issue, you need to use @moduledoc do document your modules, as I already said earlier.

1 Like
7

You can add @moduledoc false and credo will skip the module’s documentation, not showing the warning.

3 Likes
8

This will also specifically prevent the module from even being listed in generation documentation and some other lookups as well.

3 Likes
9

For who like me doesn’t want to open all files one by one and type that:

#!/bin/bash

# acting on all files under lib/
IFS=$'\n'
SUBB='Modules should have a @moduledoc tag.'

for line in $(mix credo list --format oneline)
do
   if [[ "$line" == *"$SUBB"* ]]; then
      path_to_file=$(echo "$line" | grep -P '((lib)+[\/a-z0-9._]+)+(\/?){1}' -o)

      sed -i '2 i\  @moduledoc false\n' $path_to_file
   fi
done

The separator is 2 whitespaces (others prefer tabs)
it gets all files under lib

1 Like
10

Add this to your .credo.exs file:

{Credo.Check.Readability.ModuleDoc, false}

Put a false near to the Credo.Check.Readability.ModuleDoc

This would disable checks for module docs.

11

Is there a way to disable this rule (or generally a credo rule) for tests?
I don’t really see the point in adding a module documentation to my tests since they always map 1:1 to a module, which is documented.
For now I’m just putting @moduledoc false in every test file but maybe there is a nicer way?

12

What version of credo are you using? I’m not sure for how long, but that specific check ignores all .exs files which tests are conventionally saved as.

1 Like
13

I’ve seen that error pop up within VSCode and plugins, it was usually when it mixed something up - so it wouldn’t appear when run on the CLI and also disappear when the editor was launched again :slight_smile:

1 Like
14

That’s very strange! The first line is a check on the file extension, so there must be something fishy going on for this to fail.

def run(%SourceFile{filename: filename} = source_file, params \\ []) do
  if Path.extname(filename) == ".exs" do
    []
  else
    # ...
  end
end

I’ve never used vcode so I obviously have no appetite to investigate, but definitely very odd that could fail.

15

Ah! It seems that’s exactly the issue for me, I don’t get the error when I run mix credo, it just shows up through the Vscode plugin I’m using (Credo (Elixir Linter) - Visual Studio Marketplace).

Maybe I have configured something wrong, I’ll look into it, thank you for the pointer!

16

You don’t define only .exs files in your tests, all the fixtures, helpers and other things that you need to reference are always .ex files, and credo rules apply to them.

17

True that! The /test directory is included by default, though, so I guess it’s encouraged to doc those? I just checked a project and I have have actual docs for them some and false for others. Though ya, /test won’t be included in exdoc so not sure the utility of it or why that is the default.

¯\(ツ)/¯

18

Hard to tell.

I was thinking up to this point that helpers like this one phoenix/lib/phoenix/test/channel_test.ex at v1.4.16 · phoenixframework/phoenix · GitHub were located in the test directory, as it wouldn’t make sense to have access to this functionality in your application code, but it seems this is not supported at the moment.

In my latest project we have helpers like this one, and I placed all of them in the /test directory, so you can’t use them in the application code as they don’t get compiled.

As for documentation, I think that in this case it is a net positive, even if the only way it can be treated is as commentaries when looking at source-code.

1 Like