# Documenting identical methods: unexpected change to @doc in 1.11.0

**URL:** <https://discourse.julialang.org/t/documenting-identical-methods-unexpected-change-to-doc-in-1-11-0/121309>\
**Category:** General Usage\
**Tags:** documenter, docstring\
**Created:** [October 14, 2024, 10:16pm UTC](https://discourse.julialang.org/t/documenting-identical-methods-unexpected-change-to-doc-in-1-11-0/121309 "2024-10-14T22:16:47Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![brainandforce](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/brainandforce/32/211054_2.png) [@brainandforce](https://discourse.julialang.org/u/brainandforce)\
**Post date:** [October 14, 2024, 10:16pm UTC](https://discourse.julialang.org/t/documenting-identical-methods-unexpected-change-to-doc-in-1-11-0/121309/1 "2024-10-14T22:16:47Z")

</div>

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)`:

```julia
"""
    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.

---

<div class="post-metadata">

**Author:** ![goerz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/goerz/32/3269_2.png) [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [October 15, 2024, 1:56am UTC](https://discourse.julialang.org/t/documenting-identical-methods-unexpected-change-to-doc-in-1-11-0/121309/2 "2024-10-15T01:56:12Z")

</div>

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

```julia
"""
    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.

---

<div class="post-metadata">

**Author:** ![brainandforce](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/brainandforce/32/211054_2.png) [@brainandforce](https://discourse.julialang.org/u/brainandforce)\
**Post date:** [October 16, 2024, 9:14pm UTC](https://discourse.julialang.org/t/documenting-identical-methods-unexpected-change-to-doc-in-1-11-0/121309/3 "2024-10-16T21:14:05Z")

</div>

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