ExDoc inserting child_spec/1 into generated docs. How to suppress?

Questions / Help
1

I just started using ExDoc and it is great! Just one problem so far:

When I run “mix docs” documentation is generated for the child_spec/1 function coming from using the GenServer module. That is, I have no child_spec/1 function in the module.

Is there some way to suppress this?

child_spec
child_spec745×327 33.4 KB

2

Yes! The @doc ... written immediately before the use GenServer will be attached to the child_spec/1 function that is generated. (source: the ‘how to supervise’ section of the GenServer module docs)

If you add @doc false then ExDoc won’t document a function (and won’t list it). So if you add @doc false immediately before the use GenServer line, the documentation for child_spec will be suppressed.

EDIT: However, if you do this, it might be worthwhile to at the very least document in the module docs that this is a GenServer module that can be started under a supervisor in the normal way.

3 Likes
3

Nice! Thanks.

4

Another way to do it, that may be more obvious, is to override the function and mark it:

@doc false
def child_spec(opts), do: super(opts)
5

As the function is generated, you actually have that function in the compiled module. Why not keep the docs then?

6

Just my judgement call. I suspect my initial audience won’t be interested in that.