How do I document test modules?

Questions / Help
1

I’m looking at someone else’s test module and at the top they have

  @moduledoc false

I assume this is because the tests are internal and documentation is not supposed to be exposed to the outside.

So if I want to give comments to other developers about what this module does am I supposed to just use many #? Is there a better way if I have lots of lines of comments?

2

Why not just use moduledoc as normal?

3

You are being way too sheepish here. If you feel a module should have docs, make it have docs. Nobody is going to bludgeon you to death because you wanted to improve code readability.

Also there’s nothing wrong with comments either but they don’t get automatically surfaced when you generate docs for your module(s).

4

There was one time I added @moduledoc false to all my test modules, and it was because Credo was harassing me about it. So maybe that’s the reason?

5

Sure, that might be, but OP is asking if they are “supposed” to use comments and not module docs.

I say if module docs are really needed, go for them.

1 Like
6

So this project was written by someone else who has since left. I checked and credo is a dependency. So what did you do? Do you comment test modules differently?

7

One of Credo’s default rules is that all modules should have a @moduledoc:

https://hexdocs.pm/credo/Credo.Check.Readability.ModuleDoc.html

Since test modules don’t really need a @moduledoc (Disclaimer: I’m not a seasoned veteran), I just put @moduledoc false so that Credo would shut up.

Having gained some experience since the last time I used Credo, what I would do now is to relax those rules a bit. Maybe disable the rule in the test modules at least (I don’t know the specifics of customizing Credo rules, but I know that it can be done to some degree or another).

But I don’t think there is a particularly compelling reason to require a @moduledoc tag for a test module. Like @dimitarvp said, if you need one, then use one. Otherwise, it’s just unnecessary cruft IMO.

EDIT: Relevant link with tips on removing the rule (if that’s your thing):

1 Like