MichaelHatherly / Lexicon.jl

Julia package documentation generator.
Other
16 stars 18 forks source link

Showing signatures does not resolve typealias #128

Open hayd opened 9 years ago

hayd commented 9 years ago

see https://github.com/JuliaGraphs/LightGraphs.jl/pull/109#issuecomment-128452527

julia> typealias Foo Union{Int32, Int64}
Union{Int64,Int32}

julia> Foo
Union{Int64,Int32}

julia> function f(x::Foo) end
f (generic function with 1 method)

julia> methods(f)
#1 method for generic function "f":
f(x::Union{Int64,Int32})

In Lexicon's output it would be preferable to render this as f(x::Foo).

MichaelHatherly commented 9 years ago

Isn't this more of a Julia issue? Lexicon is just using the default display methods. I'm not even sure how you'd go about getting the binding back from Foo.

sbromberger commented 9 years ago

The crux of the issue here is that this behavior exposes internal structure decisions. For example, I use a different structure for edges in LightGraphs depending on what version of Julia is in use: for 0.4, we use typealias Edge Pair{Int, Int}; for 0.3, I use an Edge type I created myself. When the documentation is generated, it is built using 0.4 and therefore I get

dst(e::Pair{Int64,Int64})

when what I really would like is

dst(e::Edge)

or even

dst(e)

since I describe the arguments to the function in the doc text itself.

hayd commented 9 years ago

Is there a way to list type aliases defined in a module, we could iterate through them and use regex... assuming there's not a huge number of them :s

MichaelHatherly commented 9 years ago

You could look for symbols that don't match the name of the object that they're bound to.

julia> for n in names(Base)
           obj = getfield(Base, n)
           if isa(obj, DataType)
               obj.name.name != n && println(n, " -> ", obj)
           end
       end
=> -> Pair{A,B}
Base64Pipe -> Base.Base64.Base64EncodePipe
BitMatrix -> BitArray{2}
BitVector -> BitArray{1}
Cchar -> Int8
Cdouble -> Float64
Cfloat -> Float32
Cint -> Int32
Cintmax_t -> Int64
Clong -> Int64
Clonglong -> Int64
Coff_t -> Int64
Complex128 -> Complex{Float64}
Complex32 -> Complex{Float16}
Complex64 -> Complex{Float32}
Cptrdiff_t -> Int64
Cshort -> Int16
Csize_t -> UInt64
Cssize_t -> Int64
Cuchar -> UInt8
Cuint -> UInt32
Cuintmax_t -> UInt64
Culong -> UInt64
Culonglong -> UInt64
Cushort -> UInt16
Cwchar_t -> Int32
Dims -> Tuple{Vararg{Int64}}
FileOffset -> Int64
FloatingPoint -> AbstractFloat
IOBuffer -> Base.AbstractIOBuffer{Array{UInt8,1}}
MathConst -> Irrational{sym}
MemoryError -> OutOfMemoryError
Nothing -> Void
String -> AbstractString
UdpSocket -> UDPSocket
Uint -> UInt64
Uint128 -> UInt128
Uint16 -> UInt16
Uint32 -> UInt32
Uint64 -> UInt64
Uint8 -> UInt8
UnionType -> Union
WString -> UTF32String

Kind of works, not sure how accurate it is though.

MichaelHatherly commented 9 years ago

I still think the display issue is more related to Julia than Lexicon:

Normal method signatures at the REPL don't display the actual typealiases, always the underlying type:

julia> typealias Edge Pair{Int, Int}
Pair{Int64,Int64}

julia> f(::Edge) = ()
f (generic function with 1 method)

julia> methods(f)
# 1 method for generic function "f":
f(::Pair{Int64,Int64}) at none:1
sbromberger commented 9 years ago

@MichaelHatherly:

I still think the display issue is more related to Julia than Lexicon.

Oh, I agree wholeheartedly. For examining / debugging Julia code, it's useful. For documentation that's trying to expose a higher-level API to users, it's not. :)

hayd commented 9 years ago

Hmmm, the above doesn't handle parametrised types i.e. TypeConstructors, but I think that should just about work. Certainly will work for this case. :)

Agree this is a Julia issue, though it's easier to get a solution here (on the documentation side). In the Base example above there are some alias which map to the same type i.e. there is no inverse. So I'm not sure whether this is fixable (in base). :s

MichaelHatherly commented 9 years ago

Yeah, it's not a 1-1 mapping. If we know which module we're dealing with then there are at least fewer to have to choose from. Hopefully a package doesn't go a define dozens of aliases for the same thing...

I'm fine with adding something in the package to deal with signatures better. I've been wanting to improve things like line-breaking in long signatures and nicer indentation anyway, so this can go along with those changes when they happen.

hayd commented 9 years ago

Now that Union order is well-defined (in julia master), one way is to use regex on the strings (the tricky bit is the T... but for simple cases it should be ok) :s