Unable to document Base methods from another module?

[johnmyleswhite]

I've found that attempts to document methods from Base while in another module fail:

julia> @doc """
       Foo
       """ ->
       function Base.sum(a::Vector{Int})
           return NaN
       end
ERROR: `doc` has no method matching doc(::Module, ::Void, ::MD, ::Expr)
 in anonymous at docs.jl:40

Is this a bug? Or am I using @doc improperly?

[MichaelHatherly]

That should probably work I'd think. cc @one-more-minute. I've not implemented this in Docile either though. Where should the docstring end up? In Base or the module where sum is being extended from?

[MikeInnes]

From the error it looks like @doc is pulling out the function name as Base rather than sum. If you import Base.sum and extend it directly it should work. (but yes, this is a bug)

@MichaelHatherly Doc strings are always stored in the module they were defined (I'm hoping this will interact well with module caching). So in this case the extending module gets a new FuncDoc for sum, and retreiving the documentation scans all modules for method meta.

[johnmyleswhite]

Glad this is a bug. I try to avoid using import.

[MikeInnes]

@johnmyleswhite Ok, this should work fine now.

By the way, while you're trying this out, I think DataFrames makes a great use case for using interpolation to show examples, e.g.

@doc doc"""
  Let's apply `foo` to a dataframe like this:

  $(DataFrame(A=["a","b"],B=[1,2]))
  """ ->
foo() ...

This just makes it really easy to give examples that work in the terminal, Juno/IPython, whatever. If you get a chance to have a go with this I'd love to hear what you think.

[MichaelHatherly]

@one-more-minute thanks for the explanation. That's basically what I've been doing, apart from keeping a reference to documented modules. Makes things a bit cleaner than what I've been doing, so I'll probably change over to using that in Docile.

[johnmyleswhite]

@one-more-minute: I'll try to use those kind of examples in DataFrames when I get back to it. Have a couple of other projects to finish first, which I'm documenting using these tools to get a sense for how to use them.