Documenter handling Internal (private) modules

General Usage
, ,
1

I am working on the documentation for module that mostly just bridges the gap between Julia and a C library. There are two methods that I expose that are fully written in Julia because they do not have a counterpart in in the C library but provide functionality that is needed.

These two methods share a bunch of other methods to do what they need to do. So I put all this code in an “internal” module which just exports the two important public methods. Then the parent module re-exports those methods so that the client can easily access this functionality.

The issue is that the Documenter, when listing those two functions, prefixes them with the internal module even though the caller doesn’t need to know about module at all. I’ve searched the Documenter instructions and so far haven’t stumbled upon any flag I could pass to makedocs or @docs to trim the module from the name. Anyone know of a way to handle this? Or is the recommendation to just move the exported function up to the main module?

Basically I have this:

module MyModule

module InternalMod
    export func1

    """
        func1()
    """
    function func1() = 1

end

using .InternalMod
export func1

end

When using @docs in the markdown documentation for func1 the function name is MyModule.InternalMod.func1() and I would prefer to just have MyModule.func1().

2

Or is the recommendation to just move the exported function up to the main module?

Yeah, that’s currently the only way. However, you can always just declare the (public) functions with function func1 end in the main module and then implement the methods in the submodule. I.e.

module MyModule

export func1
function func1 end

module InternalMod
    import ..MyModule: func1
    """
        func1()
    """
    function func1()
        return 1
    end
end

end

Just a small design philosophy note: Documenter tries to accurately reflect the code in this situation. If a function is defined in MyModule.InternalMod, then Documenter should state that. A feature that would allow you to fudge that information seems counterproductive to me. I think that a slight reorganization of the code is the cleaner solution.

1 Like