Documenting identical methods: unexpected change to @doc in 1.11.0

General Usage
,
1

In CliffordNumbers.jl, Base.reverse implements the reverse operation on a Clifford number or indexing object (BitIndex). For convenience, I’ve also overloaded the adjoint operator '.

Because the documentation for adjoint(::BitIndex) and reverse(::BitIndex) are identical, I’ve used to @doc macro to apply the original docstring to reverse(::BitIndex):

"""
    adjoint(i::BitIndex) = reverse(i::BitIndex) = i' -> BitIndex
    adjoint(x::AbstractCliffordNumber) = reverse(x::AbstractCliffordNumber) = x' -> typeof(x)

Performs the reverse operation on the basis blade indexed by `b` or the Clifford number `x`. The 
sign of the reverse depends on the grade of the basis blade `g`, and is positive for `g % 4 in 0:1`
and negative for `g % 4 in 2:3`.
"""
adjoint(i::BitIndex) = typeof(i)(xor(signbit(i), !iszero(grade(i) & 2)), UInt(i))
reverse(i::BitIndex) = adjoint(i)
@doc (@doc adjoint(::BitIndex)) reverse(::BitIndex)

This worked fine until 1.11 dropped, and now I face two problems:

  • Accessing help for reverse from the REPL now includes docstrings for all of the documented methods of adjoint/the ' operator, not just adjoint(::BitIndex).
  • Documenter.jl does not think that I’ve actually documented the method reverse(::BitIndex).

I assume the behavior of @doc has changed Is the way I’m doing things a hack that I shouldn’t be using? I’d like a more robust way to reuse docstrings if possible.

2

I’m not saying this isn’t a regression in 1.11 that should be fixed, but I would still recommend just giving adjoint and reverse two different docstrings

"""
    reverse(i::BitIndex) = i' -> BitIndex

Performs the reverse operation on the basis blade indexed by `b` or the Clifford number `x`. The 
sign of the reverse depends on the grade of the basis blade `g`, and is positive for `g % 4 in 0:1`
and negative for `g % 4 in 2:3`.
"""
reverse(i::BitIndex) = typeof(i)(xor(signbit(i), !iszero(grade(i) & 2)), UInt(i))


"""
    adjoint(i::BitIndex)

is an alias for [`reverse(::BitIndex)`](@ref).
"""
adjoint(i::BitIndex) = reverse(i)

I’ve taken the liberty of making reverse the “primary” function, and I’d have to play around with what link to reverse makes the correct cross-reference, but you get the picture.

3 Likes
3

Thanks! I wasn’t sure about this being a regression, but either way I’d like to follow best practices for documentation.