Function must be explicitly imported to be extended

[dpo]

I'm not sure if this should be reported here or on the Lexicon tracker. I'm writing a module with a function named factorize. Julia doesn't have any complaints about it when I import the module, but when I document it and try to generate HTML documentation, I get

ERROR: error in method definition: function LinAlg.factorize must be explicitly imported to be extended

In this particular case, it does happen that my factorize is related to LinAlg.factorize, but what if it weren't (e.g., if its purpose were to factor integers or polynomials)?

The only workaround I've found so far is to use @doc*, but that lists my function separately from the rest.

I'm not sure I understand why I would need to import LinAlg.factorize at all. That's what namespaces are for, isn't it?

[MichaelHatherly]

This appears to be caused by calling methods(factorize) prior to trying to define a new method called factorize. (See here)

I can cause the same error by doing the following at a fresh REPL:

               _
   _       _ _(_)_     |  A fresh approach to technical computing
  (_)     | (_) (_)    |  Documentation: http://docs.julialang.org
   _ _   _| |_  __ _   |  Type "help()" for help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 0.3.5-pre+110 (2014-12-31 01:04 UTC)
 _/ |\__'_|_|_|\__'_|  |  Commit e06ec74 (1 day old release-0.3)
|__/                   |  x86_64-unknown-linux-gnu

julia> methods(factorize)
# 7 methods for generic function "factorize":
factorize{T}(A::Array{T,2}) at linalg/dense.jl:334
factorize(S::SymTridiagonal{T}) at linalg/ldlt.jl:31
factorize(A::Triangular{T,S<:AbstractArray{T,2},UpLo,IsUnit}) at linalg/triangular.jl:313
factorize(A::Tridiagonal{T}) at linalg/lu.jl:222
factorize(A::Union(Symmetric{T},Hermitian{T})) at linalg/symmetric.jl:39
factorize(D::Diagonal{T}) at linalg/diagonal.jl:39
factorize(A::SparseMatrixCSC{Tv,Ti<:Integer}) at linalg/cholmod.jl:1071

julia> factorize(a, b, c, d, e) = ()
ERROR: error in method definition: function LinAlg.factorize must be explicitly imported to be extended

Curiously 0.4 doesn't appear to suffer from this:

              _
   _       _ _(_)_     |  A fresh approach to technical computing
  (_)     | (_) (_)    |  Documentation: http://docs.julialang.org
   _ _   _| |_  __ _   |  Type "help()" for help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 0.4.0-dev+2340 (2014-12-31 04:12 UTC)
 _/ |\__'_|_|_|\__'_|  |  Commit 3109867 (1 day old master)
|__/                   |  x86_64-unknown-linux-gnu

julia> methods(factorize)
# 7 methods for generic function "factorize":
factorize{T}(A::Array{T,2}) at linalg/dense.jl:338
factorize(S::Base.LinAlg.SymTridiagonal{T}) at linalg/ldlt.jl:31
factorize(A::Base.LinAlg.Triangular{T,S<:AbstractArray{T,2},UpLo,IsUnit}) at linalg/triangular.jl:532
factorize(A::Base.LinAlg.Tridiagonal{T}) at linalg/lu.jl:224
factorize(A::Union(Base.LinAlg.Symmetric{T,S},Base.LinAlg.Hermitian{T,S})) at linalg/symmetric.jl:47
factorize(D::Base.LinAlg.Diagonal{T}) at linalg/diagonal.jl:39
factorize(A::Base.SparseMatrix.SparseMatrixCSC{Tv,Ti<:Integer}) at linalg/cholmod.jl:1071

julia> factorize(a, b, c, d, e) = ()
factorize (generic function with 8 methods)

Could you provide the output of versioninfo() so we can see whether this is specific to Linux or a cross platform issue?

[MichaelHatherly]

Most recent builds, namely 0.3.5-pre+113 and 0.4.0-dev+2358, also exhibit this behaviour.

[dpo]

I'm on OSX 10.10 with homebrew Julia:

julia> versioninfo()
Julia Version 0.3.3
Commit b24213b* (2014-11-23 20:19 UTC)
Platform Info:
  System: Darwin (x86_64-apple-darwin14.0.0)
  CPU: Intel(R) Core(TM) i7 CPU       M 620  @ 2.67GHz
  WORD_SIZE: 64
  BLAS: libopenblas (NO_AFFINITY NEHALEM)
  LAPACK: libopenblas
  LIBM: libopenlibm
  LLVM: libLLVM-3.3

[MichaelHatherly]

Given the differences between 0.3 and 0.4 behaviour I'd think it's worth filing an issue in the julia repo itself with the reduced example. I'll file one tomorrow morning unless you've already done so by then.

[MichaelHatherly]

@dpo, the latest push to Docile master contains a new plain string implementation of docstrings. From what I can tell this problem is resolved when using the new system (though there may be others lurking).

Unfortunately Lexicon will need a little work to be able to talk to Docile; that's what I'll be up to over the next few days. If you fancy living on the edge you can check out Docile master and try documenting things using:

module MyModule

using Docile
@document # place at start of module

"foobar's documentation"
foobar(x, y) = x + y

end

[Edit: change to Docile interface.]

I'm sorry for the hassle this has caused.

[dpo]

Many thanks for the hard work. No rush on my end. What you currently have is infinitely better than no documentation, so I can be patient. I don't mind living on the edge, but I suspect my users will run into problems because they'll have the release version of Docile.

[MichaelHatherly]

Yes, that would cause trouble for users. The next release shouldn't be too far away though.