Feature Request: Support Combined Assignment and Multi-Variable Documentation in `@doc`

[ilyagarazha]

Currently, Julia’s @doc macro supports two useful patterns:

1. Assigning a value while adding a docstring:

   @doc "Square root of pi" sqr_pi = √π

2. Documenting multiple unassigned variables:

   @doc "Parameter of PID controller" K_p, K_i, K_d

However, combining these two features — assigning values and documenting multiple variables with a single docstring — is not supported. For example:

@doc "Parameter of PID controller" K_p, K_i, K_d = 1, 2, 3

…currently only attaches the docstring to K_p, while K_i and K_d remain undocumented, even though they are logically part of the same conceptual group.

Desired Behavior

The macro should allow a docstring to be applied to all variables in a multi-assignment expression:

@doc "Parameter of PID controller" K_p, K_i, K_d = 1, 2, 3

→ This should attach the same docstring to K_p, K_i, and K_d (just like @doc "..." x, y does for unassigned variables).

Why This Matters

This would improve code clarity and maintainability, especially in scientific or control systems code, where related constants are often defined and documented together. It avoids repetition and keeps documentation logically grouped with the variables it describes.

Example Use Case

@doc """
    PID controller gains.
    K_p: Proportional gain
    K_i: Integral gain
    K_d: Derivative gain
""" K_p, K_i, K_d = 1.0, 0.1, 0.01

Currently, only K_p gets the docstring. With this enhancement, all three would be properly documented in ?K_p, ?K_i, and ?K_d.

[nsajko]

I think it is rare to want to attach the same doc string to multiple different bindings.

Your example problem could be solved with @eval:

for (subscript, description, value) in [("p", "proportional gain", 1.0), ("i", "integral gain", 0.1), ("d", "derivative gain", 0.01)]
    name = string("K_", subscript)
    name_sym = Symbol(name)
    @eval begin
        """
            $($name)

        PID controller gain: $($description).
        """
        $name_sym = $value
    end
end

Results:

julia> K_i
0.1

help?> K_i
search: K_i K_p K_d

  K_i

  PID controller gain: integral gain.