Suppress errors for unexported functions

[lelogrott]

Is there a way to suppress errors about missing documentation for unexported functions?

[mortenpi]

You shouldn't be getting errors if you are not referring to them in an @docs block. For an @autodocs block you can, you can specify the Private option to ignore unexported options. Do you have an example build?

[lelogrott]

@mortenpi
Yep. The function below gets cited as having a docstring potentially missing.

.jl file: https://github.com/JuliaGraphs/LightGraphs.jl/blob/e828bd242472d71a7b05e3da93bd43d969f99481/src/flow/maximum_flow.jl#L54

.md file:
https://github.com/JuliaGraphs/LightGraphs.jl/blob/e828bd242472d71a7b05e3da93bd43d969f99481/docs/src/flowcut.md

[lelogrott]

@mortenpi any news about those errors?

[tkf]

I think I have the same issue. Here is an MWE (full repository in https://github.com/tkf/MyPlayground.jl/tree/documenter-private):

docs/src/index.md:

# MyPlayground.jl

```@autodocs
Modules = [MyPlayground]
Private = false
```

src/MyPlayground.jl:

module MyPlayground

export my_public_function

"""
    my_public_function()

This function is exported.
"""
my_public_function() = nothing

"""
    my_private_function()

This function is _not_ exported.
"""
my_private_function() = nothing

end # module

Without Private = false it produces no failure https://travis-ci.org/tkf/MyPlayground.jl/builds/475125156. However, unexported function is included in the documentation.

Adding Private = false (tkf/MyPlayground.jl@66dbb9d) hides the unexported function. However, Documenter now shows the warning and the build fails when strict = true is passed: https://travis-ci.org/tkf/MyPlayground.jl/builds/475125720

(The motivation behind this is that I'd like to have three kinds of bindings with docstring: (1) exported public API, (2) unexported public API, (3) unexported non-public function. I'd like to have (1) and (2) in the documentation but not (3). Or, actually, adding (3) using hide is good if there is a way to use @autodocs to dump all non-included bindings.)

[mortenpi]

@lelogrott: Apologies for not replying before. The underlying assumption is that all docstrings are meant to be public (whether that is reasonable is up for debate). As you're not including residual in the docs (since you have Private = false), Documenter thinks that you forgot to include it in the docs and gives a warning or indeed kills the build when strict = true.

In Documenter's own docs we get around this by having a separate "internals" page with the docstrings of all the private functions etc.

Having some sort of better support for public unexported names would be great though. The problem is: how would Documenter figure out which unexported names are public and which are not?

• I am not sure that having a way to including all unincluded docstrings is necessarily a good idea. I think it might be worth forcing the user to be a bit more explicit about which docstrings get included where, since otherwise it's very easy to forget to update the docs when you e.g. add a new public function.

• We could maybe have a way to explicitly ignore ( ```@docs ignore?) certain docstrings (i.e. they would not get included, but also won't cause an error; would fix the residual problem)? But on the other hand, if you already have a docstring, wouldn't it be better to include it somewhere?

[tkf]

Having some sort of better support for public unexported names would be great though.

👍

The problem is: how would Documenter figure out which unexported names are public and which are not?

How about "do not warn/error unincluded docstrings if they are not included explicitly"? This implies that API is public only if it's export'ed or manually included in the documentation. I think this is a reasonable default as this makes marking something public explicit.

But on the other hand, if you already have a docstring, wouldn't it be better to include it somewhere?

Yes, especially also for running doctests. It would be nice to have a page hide("Internals" => "internals.md") with @autodocs_internals (say; it could be just an option) which dumps all docstrings not included via other @autodocs and @docs.

[sbromberger]

Hi all, I'm chiming in here because I'm a bit confused.

In LightGraphs, I get

┌ Warning: 115 docstrings potentially missing:
│
...
│     LightGraphs.random_greedy_color :: Union{Tuple{T}, Tuple{AbstractGraph{T},Integer}} where T<:Integer
...

but

~/.julia/dev/LightGraphs/src$ grep random_greedy_color LightGraphs.jl
~/.julia/dev/LightGraphs/src$

~/.julia/dev/LightGraphs/docs$ grep -Ri random_greedy_color *
~/.julia/dev/LightGraphs/docs$

(That is, random_greedy_color() is 1) unexported, and 2) not referenced anywhere in the docs source). We have Private = false wherever we have @autodocs.

How do I suppress these warnings? (There are 115 of them, and most - if not all - are unexported functions for which we do not intend to write docstrings.)

[JosePereiraUA]

Hi, so, currently, our best solution is to have an "Internals" hiden page?
I would like to see something like:

@privatedoc """
    my_function()

This docstring will not be considered in `makedocs`.
"""
my_function()
    return nothing
end

This way we could ignore individual docstrings.

[nalimilan]

Now that Julia has a public keyword argument to declare unexported public API (JuliaLang/julia#50105), maybe Documenter could check only whether docstrings for public or exported functions are included?

[mortenpi]

Now that Julia has a public keyword argument to declare unexported public API (JuliaLang/julia#50105), maybe Documenter could check only whether docstrings for public or exported functions are included?

Making Documenter aware of public is definitely something we want. But since this would be a pretty significant behavior change, my current feeling is that this needs to be an opt-in via an argument.