add at-kwdef to the manual

[pierre-haessig]

I just discovered the Base.@kwdef macro (as well as the Parameters.jl package) to be able to create structs with the keyword argument syntax like Point(x=1,y=2). I don't know the long history of this macro and the reason why it was kept hidden, but it seems to have been improved recently (Julia 1.1, with #29316) to the point where the README of Parameters.jl suggests that for the simplest use cases, Base.@kwdef is now enough.

My question is therefore: is Base.@kwdef mature enough so that it should enter Julia's manual, in particular in the Constructors section?

I understand that the hidden nature of @kwdef was useful to allow faster changes without deprecation (e.g. StefanKarpinski's response in #27970, July 2018). At the same time, there is the pending 2014 #5333 issue where StefanKarpinski's 2016 comment suggest that keyword argument constructor for immutables is a good idea. So documenting @kwdef could be a simple bridge between the absence of the feature and this feature becoming the default (in a future Julia 2.0, it this doesn't break too many things?). What do you think?

[pierre-haessig]

Thanks @KristofferC for PR #46273. However, I believe the PR only partially addresses this issue, since I see in the file changes that documentation of @kwdef is "only" added to the Base / Essentials/ §Keywords section of the manual.

Adding a subsection in the Constructors page would increase discoverability. What do you think?

[KristofferC]

Sounds like a good idea.

[pierre-haessig]

For the reference, this is the outline of the Constructors page of the manual:

• Outer Constructor Methods
• Inner Constructor Methods
• Incomplete Initialization
• Parametric Constructors
• Case Study: Rational
• Outer-only constructors

Since the docstring of @kwdef mentions Internal Constructors, an appropriate place may be between "Inner Constructor Methods" and "Incomplete Initialization". Either as a dedicated subsection, or just a small "see also" box (not sure about the syntax, does this exist in Julia manual) ?

Since their is a long discussion about the 3 use cases of constructors which spans the first three sections (Outer, Inner, Incomplete Init), a new subsection on @kwdef should be quite small, to not interrupt to much the logic. Or a use a sub-sub-section ?

Perhaps a better placement: between "Incomplete Initialization" and "Parametric Constructors" since the latter starts a new topic (starts with "Parametric types add a few wrinkles to the constructor story.")

[vtjnash]

I would encourage still writing that doc as you described, but I don't think we need an option issue about it