Struct with @kwdef does not follow template

[bzinberg]

At the moment there are no tests for #73, right?

Base.@kwdef uses @__doc__ so this should cover that issue.

Originally posted by @MichaelHatherly in #96 (comment)

Compared DocStringExtensions from current release and from master. In both cases, this

import DocStringExtensions
import DocStringExtensions: SIGNATURES, TYPEDSIGNATURES, DOCSTRING,
    FIELDS, TYPEDFIELDS
DocStringExtensions.@template TYPES =
    """
    Fields:
    $(TYPEDFIELDS)

    ---

    $(DOCSTRING)
    """

@doc """
Camera configuration.

Defines the intrinsics and extrinsics of an ideal pinhole camera.
""" CameraConfig
@kwdef struct CameraConfig
  """Pose (position and orientation) of the camera eye."""
  cameraEyePose::Pose
  intrinsics::CameraIntrinsics
end

becomes this

[bzinberg]

Same also applies if I replace

@doc "..." CameraConfig
@kwdef struct CameraConfig ... end

with

@doc "..."
@kwdef struct CameraConfig ... end

[MichaelHatherly]

Can you confirm that you are at 339cd6d for master?

With this test file:

module Test

import Base: @kwdef
using DocStringExtensions

abstract type Pose end
abstract type CameraIntrinsics end

@template TYPES =
    """
    Fields:
    $(TYPEDFIELDS)

    ---

    $(DOCSTRING)
    """

@doc """
Camera configuration.

Defines the intrinsics and extrinsics of an ideal pinhole camera.
""" CameraConfig
@kwdef struct CameraConfig
    """Pose (position and orientation) of the camera eye."""
    cameraEyePose::Pose
    intrinsics::CameraIntrinsics
end

end

You'll note the following

julia> include("/home/mike/test.jl")
WARNING: replacing module Test.
Main.Test

julia> Docs.meta(Test)[Docs.@var(Test.CameraConfig)].docs[Union{}].data
Dict{Symbol,Any} with 5 entries:
  :typesig    => Union{}
  :module     => Main.Test
  :linenumber => 19
  :binding    => Main.Test.CameraConfig
  :path       => "/home/mike/test.jl"

:fields is not captured since the @doc call does not capture the actual struct definition. This is a limitation how the docsystem works. If you instead apply the docstring directly to the definition:

"""
Camera configuration.

Defines the intrinsics and extrinsics of an ideal pinhole camera.
"""
@kwdef struct CameraConfig
    """Pose (position and orientation) of the camera eye."""
    cameraEyePose::Pose
    intrinsics::CameraIntrinsics
end

julia> include("/home/mike/test-2.jl")
Main.Test2

julia> Docs.meta(Test2)[Docs.@var(Test2.CameraConfig)].docs[Union{}].data
Dict{Symbol,Any} with 6 entries:
  :typesig    => Union{}
  :module     => Main.Test2
  :linenumber => 0
  :binding    => Main.Test2.CameraConfig
  :path       => ""
  :fields     => Dict(:cameraEyePose=>"Pose (position and orientation) of the camera eye.")

And the template is correctly applied:

help?> Test2.CameraConfig
  Fields:

    •    cameraEyePose::Main.Test2.Pose

        Pose (position and orientation) of the camera eye.

    •    intrinsics::Main.Test2.CameraIntrinsics

  ─────────────────────────────────────────────────────────────────

  Camera configuration.

  Defines the intrinsics and extrinsics of an ideal pinhole camera.

@doc "..."
@kwdef struct CameraConfig ... end

That is not the right syntax to add a docstring to CameraConfig. Your @doc "..." doesn't apply to the next line, here it is just searching the docsystem for a docstring attached to "...", which won't find anything.

---

Bottom line is: don't use @doc when you're trying to document things, it'll likely be do the wrong thing. Just use bare strings above definitions. Hope that all helps.

[bzinberg]

Thanks for these responses @MichaelHatherly!

I'm pretty sure I'm on the latest revision:

pkg> add DocStringExtensions#master
pkg> status DocStringExtensions
  ...
  [ffbed154] DocStringExtensions v0.8.2 `https://github.com/JuliaDocs/DocStringExtensions.jl.git#master`

Manifest.toml says it's using git tree hash 8990557a11a984254a2fa4f69f24ff861b080a03. I'm not sure how to map that to a commit, and people seem to struggle with that on Discourse as well.

Here's what I'm seeing:

Works

1. """My docstring"""
   @kwdef struct CameraConfig ... end

2. """$(raw"""My docstring with ``\LaTeX``""")"""
   @kwdef struct CameraConfig ... end

3. @doc(raw"""My docstring with ``\LaTeX``""",
   @kwdef struct CameraConfig ... end)

   (Thanks for pointing out that the non-parentheses macro invocation syntax doesn't work here)

Doesn't work

1. raw"""My docstring with ``\LaTeX``"""
   @kwdef struct CameraConfig ... end

   (no docstring gets attached -- intentional on the part of Julia)

Unfortunately, through no fault of this package, I'm not going to be able to use the good versions until JuliaLang/julia#36906 is fixed upstream -- having the wrong view source link is too big of a problem, so I'm stuck with the @doc "..." CameraConfig; @kwdef struct CameraConfig ... end workaround which loses field docstrings. Thanks for fixing the issue in DocStringExtensions and for explaining all the above!

[MichaelHatherly]

Unfortunately, through no fault of this package, I'm not going to be able to use the good versions until JuliaLang/julia#36906 is fixed upstream

JuliaLang/julia#37048 should hopefully resolve that one.

[bzinberg]

Omg, thanks!!