make module docstring an exception from checkdocs = :exports

[tpapp]

It is useful to include a docstring for a module, eg

"""
The main entry point for this module is `MyMod.do_stuff()`.

For details, please read the docs.
"""
module MyMod
    # ...
end

However,

makedocs(modules = [MyMod],
         checkdocs = :exports,
         strict = true,
         ...)

will complain about MyMod.MyMod if this docstring is not referenced.

Since it usually does not make much sense to include it in the generated docs, I wonder if it could be made an exception.

[tpapp]

Still could not figure out a workaround for this. Perhaps something like

MyMod.MyMod # hide

would be nice (but currently does not work).

[tpapp]

I would be happy to make a PR, but would appreciate some advice on

1. how to handle this for the interface (an ignore list in makedocs? a # hide in ```@docs?),
2. where to start implementing it.

[mortenpi]

Sorry for not replying earlier -- I wasn't entirely sure how I felt about the proposal. In my opinion, you should just include the module docstring, e.g. as a last thing on the index page. Otherwise, you'll probably end up duplicating whatever is in there.

However, the ability to tell checkdocs to ignore a few docstrings could be handy, also in other situations.

I don't think # hide in an at-docs block is the way to go though -- you're deciding not to include something you just included? Also, you're configuring something that is global to the whole document.

An argument to makedocs makes probably the most sense. It could perhaps be a quote ... end expression, using the same syntax as in an at-docs block? The same machinery could then be used to parse it (might need some refactoring; see Expanders.jl).

[tpapp]

Reviving this old issue. I would still find this functionality useful.

As for the API, a list of symbols to ignore, to be provided as an argument to makedocs, would make the most sense for me.