Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bad docstring path/linenumber if in macro call #36906

Closed
mortenpi opened this issue Aug 4, 2020 · 1 comment · Fixed by #37048
Closed

Bad docstring path/linenumber if in macro call #36906

mortenpi opened this issue Aug 4, 2020 · 1 comment · Fixed by #37048

Comments

@mortenpi
Copy link
Contributor

mortenpi commented Aug 4, 2020

The filename and line numbers for a docstring are not properly stored if the definition is wrapped in a macro call, e.g. in the following case:

"""
    struct A
"""
Base.@kwdef struct A
  a::Int = 1
end

For an MWE, include-ing this:

"""
    struct A
"""
Base.@kwdef struct A
  a::Int = 1
end

"""
    struct B
"""
struct B
  a::Int
end

Base.@kwdef struct C
  a::Int = 1
end

@doc """
    struct C
""" C

will lead to this when fetching the docstring metadata (note the missing :path and :linenumber for A):

julia> @doc(A).meta[:results][1].data
Dict{Symbol,Any} with 6 entries:
  :typesig    => Union{}
  :module     => Main
  :linenumber => 0
  :binding    => A
  :path       => ""
  :fields     => Dict{Any,Any}()

julia> @doc(B).meta[:results][1].data
Dict{Symbol,Any} with 6 entries:
  :typesig    => Union{}
  :module     => Main
  :linenumber => 14
  :binding    => B
  :path       => "/home/mortenpi/Julia/test/test.jl"
  :fields     => Dict{Any,Any}()

julia> @doc(C).meta[:results][1].data
Dict{Symbol,Any} with 5 entries:
  :typesig    => Union{}
  :module     => Main
  :linenumber => 25
  :binding    => C
  :path       => "/home/mortenpi/Julia/test/test.jl"

X-ref: JuliaDocs/Documenter.jl#1374

@bzinberg
Copy link
Contributor

bzinberg commented Aug 9, 2020

The C solution loses field docstrings: after changing the included code to

"""
    struct A
"""
Base.@kwdef struct A
  """A well-documented integer."""
  a::Int = 1
end

"""
    struct B
"""
struct B
  """A well-documented integer."""
  a::Int
end

Base.@kwdef struct C
  """A well-documented integer."""
  a::Int = 1
end

@doc """
    struct C
""" C

we have

julia> @doc(A).meta[:results][1].data[:fields]
Dict{Symbol,String} with 1 entry:
  :a => "A well-documented integer."

julia> @doc(C).meta[:results][1].data[:fields]
ERROR: KeyError: key :fields not found
Stacktrace:
 [1] getindex(::Dict{Symbol,Any}, ::Symbol) at ./dict.jl:477
 [2] top-level scope at REPL[3]:1

MichaelHatherly added a commit to MichaelHatherly/julia that referenced this issue Aug 19, 2020
Fixes JuliaLang#36906, where source info wasn't being passed through
at-doc when it was applied to definitions defined within macros.
StefanKarpinski pushed a commit that referenced this issue Aug 19, 2020
Fixes #36906, where source info wasn't being passed through
at-doc when it was applied to definitions defined within macros.
simeonschaub pushed a commit to simeonschaub/julia that referenced this issue Aug 29, 2020
Fixes JuliaLang#36906, where source info wasn't being passed through
at-doc when it was applied to definitions defined within macros.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants