How to append the docstring of a type or function in the upstream package in a downstream package

General Usage
, ,
1

As an example, consider developing a downstream package like SpecificFoo.jl using upstream packages which provide APIs like FooBase.jl/FooCore.jl.

We can write a docstring for the method defined in the downstream package, if it is a method of public function.
Edit: e.g.

"something_public(::FooCore.AbstractFoo)" something_public # in FooCore.jl

"something_public(::SpecificFoo.Foo)" something_public(::SpecificFoo.Foo) # in SpecificFoo.jl

However, with sophisticated APIs, the internal implementation may be hidden from the end-users.
Edit: e.g.

get_most_pretty_foo(::AbstractArray{T}) where {T<:AbstractFoo} # public API for end-users

is_less_pretty(::T1, ::T2) where {T1<:AbstractFoo,T2<:AbstractFoo} # internal API for package developers

So, I believe there are demands to append docstrings to functions or types in upstream packages rather than methods in downstream packages (i.e. to write appendices).

From the current implementation of Docs, it would be technically possible, but it is “piracy”.
This means that it would be troublesome in the doc system if both SpecificFoo.jl and YetAnotherFoo.jl try to append docstrings.
(On the other hand, users will not be so troubled if docstrings are not overwritten.)

What are the best practices in the supposed case?

3

FWIW, what I’m looking for is a little like Base.Experimental.register_error_hint.
https://docs.julialang.org/en/v1/base/base/#Base.Experimental.register_error_hint

4

Well, this is not much demand and it doesn’t seem like it would be a good idea to confuse the docsystem.