Docstring for overwritten function

General Usage
1

Hi,

I am writing a Module where I am overwriting the function sample from StatsBase.jl.

To be able to overwrite the function sample I import the function in the file Modulename.jl

# import sample
import StatsBase: sample

And I implement my own sample function in another file, looking something like this


"""
    sample(inputs)

Docstring for my version of sample. 
"""
function sample(inputs)

# stuff 

end

The problem is that when I view the docstring by typing

julia> ?sample

I see both the docstring for my own implementation of sample, and the docstring for the sample function inStatsBase.jl.

Furthermore, if I type

julia> ?modulename.sample

Still, both docstrings are printed.

How can I select to only show the docstring for the function sample that I implement in my module?

2

I have no idea what the exact usage here would be, but Docs.doc! seems to be for exactly this sort of docstring replacement. Its code mentions that it replaces the docstring for a binding, though its documentation only says it adds a new docstring.

3

Why do you want to overwrite it? That is typically pretty bad, and may break things. If you want your own function called sample you can just skip importing it and defining your own. That way you will see the docstring for your function with ?ModuleName.sample.

If you instead mean to add your own method to the sample function, then you can import it and add your docstring. To query the help for just your method you can then do ?sample(args...) where args are the arguments for which your method applies to.

6 Likes
4

Thank you! This did what I wanted to do.

5

I’m in the case of needing to do the “pretty bad” thing, in GitHub - JuliaRandom/RandomExtensions.jl: Extensions to the stdlib/Random module. Indeed, the rand docstring is in one place in Random, instead of spread over at each method. This package updgrades the API, so I wish to replace fully the old docstring with a new one… if anyone has an idea?