Is it possible to add docstring to a field?

[Chen Huang]

It seems that we won't be able to add docstring to a field, possibly due to the alias functionality?

julia> using Configurations

julia> "Type TT"
       struct TT
           "x"
           x::Int
           "y"
           y::Real
       end
TT

julia> "OptionType OT"
       @option struct OT
           "x"
           x::Int
           "y"
           y::Real
       end

julia> tt = TT(1,2)
TT(1, 2)

julia> ot = OT(1,2)
OT(;
    x = 1,
    y = 2,
)

help?> TT.x
  x

help?> OT.x
ERROR: KeyError: key :fields not found
Stacktrace:
 [1] getindex(::Dict{Symbol,Any}, ::Symbol) at ./dict.jl:467
 [2] fielddoc(::Base.Docs.Binding, ::Symbol) at /Users/julia/buildbot/worker/package_macos64/build/usr/share/julia/stdlib/v1.5/REPL/src/docview.jl:458
 [3] fielddoc(::Type{T} where T, ::Symbol) at /Users/julia/buildbot/worker/package_macos64/build/usr/share/julia/stdlib/v1.5/REPL/src/docview.jl:472
 [4] top-level scope at /Users/julia/buildbot/worker/package_macos64/build/usr/share/julia/stdlib/v1.5/REPL/src/docview.jl:436

If I don't use alias, is there a way to document fields like what was describe in the language documentation?

"..."
struct T
    "x"
    x
    "y"
    y
end

[Xiu-zhe (Roger) Luo]

why do you think so? you can't document fields in Julia.

[Chen Huang]

I read about it in the Julia documentation (https://docs.julialang.org/en/v1/manual/documentation/#Types)?

[Xiu-zhe (Roger) Luo]

Hmm interesting I think somehow the lowered Expr is not the same as function docstring. There's no way to remove this feature unless you define your own macro using the codegen feature in advanced usage at the moment

But yes I need to come up with a better syntax for aliasing

[Xiu-zhe (Roger) Luo]

so it seems the field docstring is created by Docs.@doc which implicitly created by the docstring on top of the type, it won't work if you only have

struct TT
           "x"
           x::Int
           "y"
           y::Real
end

[Chen Huang]

There's no way to remove this feature unless you define your own macro using the codegen feature in advanced usage at the moment

I gave codegen a try yesterday but didn't get very far since I haven't done much metaprogramming in Julia before. I tried to remove codegen_field_alias from codegen only to realise alias was defined in OptionDef so it starts to look a little daunting. Will look into it again later.

But yes I need to come up with a better syntax for aliasing

Maybe something similar to what FieldMetadata.jl is using？a::Int | "an Int with a description" ? I did manage to make something like @description @option struct TT ... end work, but didn't like having a long line behind the field. Alias might be a better fit there, although I'm not sure if one could still keep the two packages compatible.

so it seems the field docstring is created by Docs.@doc which implicitly created by the docstring on top of the type

Yes, I realised this when making the mwe, which is a little strange indeed. Good that you've opened an issue on that. thanks:)

[Xiu-zhe (Roger) Luo]

I gave codegen a try yesterday but didn't get very far since I haven't done much metaprogramming in Julia before. I tried to remove codegen_field_alias from codegen only to realise alias was defined in OptionDef so it starts to look a little daunting. Will look into it again later.

you need to remove https://rogerluo.me/Configurations.jl/dev/advance/#Configurations.codegen_field_alias not alias, option types can have alias too. Implementing your own macro shouldn't require much knowledge of metaprogramming.

[Xiu-zhe (Roger) Luo]

Maybe something similar to what FieldMetadata.jl is using？a::Int | "an Int with a description" ? I did manage to make something like @description @option struct TT ... end work, but didn't like having a long line behind the field. Alias might be a better fit there, although I'm not sure if one could still keep the two packages compatible.

I tried it when I designing the syntax, it creates an ugly AST when combined with keywords. I might be using docstrings like Comonicon's @cast syntax instead.

[Xiu-zhe (Roger) Luo]

field alias feature is removed temporarily for the latest version.

[Fons van der Plas]

I implemented the logic to extract field docstrings here: https://github.com/JuliaPluto/PlutoSliderServer.jl/blob/29d9f5b03509036c938e199e7d6f8863a126f53b/src/ConfigurationDocs.jl#L126 though this was more with the intention of generating a list of keyword arguments automatically, not the Julia-official :field docstring, see #67