Fix: let Revise.jl parse functions and docstrings correctly

[borisdevos]

Revise.jl doesn't handle the tuple of functions with different arguments very well. I won't pretend to understand Revise internals well, but here what my robot friend told me:
"When Revise re-parses the file, it tries to evaluate that comma-tuple of signatures as a standalone expression to figure out what it documents — but a bare tuple of bodiless, where-qualified call signatures isn't valid to evaluate on its own, so it throws invalid "::" syntax and Revise gives up on the whole file (and stalls the REPL while doing so)."

This is solved by just splitting them in separate @doc blocks. Every block has 1 function with some arguments, which Revise can revise. The before and after behavior can be tested with Revise.revise(throw=true).

For obvious reasons, I want Revise to keep on revising when I'm busy in the internals. If I get a dime for every time I had to restart my REPL because of this, I'd have at least a dollar.

How the error looks like for the curious:

┌ Error: Failed to revise ...\TensorKit.jl\src\tensors\abstracttensor.jl
│   exception =
│    lowering returned an exception:
│    $(Expr(:error, "invalid \"::\" syntax"))
└ @ Revise ...\.julia\packages\Revise\yd3HH\src\packagedef.jl:1491

[lkdvos]

Thanks for this, this had also bothered me quite a bit but never quite enough to actually try looking for a solution 😆. Am I understanding this right that you are now duplicating docstrings? I think there is some way of doing this without needing to copy the text, don't quote me on the exact syntax but @doc can be used both to document and retrieve docstrings, so something like @doc (@doc method1(...)) method2(...) could also do the trick

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
src/tensors/abstracttensor.jl	54.85% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[borisdevos]

Docstrings were actually already duplicated, but now the signatures are split up, so it's somehow less duplicated 🫠 I'll look into your suggestion
Edit: I think I misunderstood what you meant, I thought you were referring to docstrings duplicating when calling ?help, but maybe you just meant code-wise?

[lkdvos]

I indeed just meant code-wise. Actually, looking at your implementation and your comment about the help section duplicating this gave me a different idea, which is to simply merge all docstrings into a single docstring, and then just having something like:

@doc """
    getindex(t::AbstractTensorMap, sectors...)
    getindex(t::AbstractTensorMap, fusiontreepair)
    ...

all merged docstrings descriptions here
""" getindex(t::AbstractTensorMap, args...)

and similar for the other ones. This avoids duplicating both the code as well as the ?help part, so should work well? If necessary the args can still be restricted with a Union or something, but I don't think that is really required here.

Apologies for derailing this PR with this by the way...

[borisdevos]

The docstring for getindex now looks like

  Base.getindex(t::AbstractTensorMap, sectors::Tuple{Vararg{Sector}})
  t[sectors]
  Base.getindex(t::AbstractTensorMap, f₁::FusionTree, f₂::FusionTree)
  t[f₁, f₂]

  Return a view into the data of t corresponding to the splitting - fusion tree pair (f₁, f₂). In particular, this is an AbstractArray{T} with T = scalartype(t), of size (dims(codomain(t), f₁.uncoupled)...,
  dims(codomain(t), f₂.uncoupled)...).

  Whenever FusionStyle(sectortype(t)) isa UniqueFusion, it is also possible to provide only the external sectors, in which case the fusion tree pair will be constructed automatically.

  │ Warning
  │
  │  Contrary to Julia's array types, the default behavior is to return a view into the tensor data. As a result, modifying the view will modify the data in the tensor.

  See also subblock, subblocks and fusiontrees.

  Base.getindex(t::AbstractTensorMap, indices::Vararg{Int})
  t[indices]

  Return a view into the data slice of t corresponding to indices, by slicing the StridedViews.StridedView into the full data array.

  Base.getindex(t::AbstractTensorMap)
  t[]

  Return a view into the data of t as a StridedViews.StridedView of size dims(t).

and for setindex!

  Base.setindex!(t::AbstractTensorMap, v, sectors::Tuple{Vararg{Sector}})
  t[sectors] = v
  Base.setindex!(t::AbstractTensorMap, v, f₁::FusionTree, f₂::FusionTree)
  t[f₁, f₂] = v

  Copies v into the data slice of t corresponding to the splitting - fusion tree pair (f₁, f₂). By default, v can be any object that can be copied into the view associated with t[f₁, f₂].

  See also subblock, subblocks and fusiontrees.

  Base.setindex!(t::AbstractTensorMap, v, indices::Vararg{Int})
  t[indices] = v

  Assigns v to the data slice of t corresponding to indices.

[borisdevos]

I just checked the docs and this might mess up the library describing these methods one by one. Is this a problem?

[lkdvos]

Probably with a slight rewording the merged docstrings could also make sense right?