Improve add_channels() docstrings

[hoechenberger]

Fixes #11106

[hoechenberger]

Docs for

• Epochs
• Evoked
• Raw
• Spectrum
• AverageTFR
• EpochsTFR

EpochsSpectrum talks about Spectrum, I need to override this

[drammock]

@hoechenberger and I just discussed this during office hours, and we're not happy with the current state of this PR --- it's better for users but extremely non-DRY. We looked around for solutions; this SO post describes our situation, but has no answers :( However, it does offer a promising suggestion in one of the comments: use type hints to specify "returns same type as self". Hopefully this will work (and not, e.g., say that it returns the Mixin class!) Curious what others think about this possible solution. Other ideas are welcome too.

[hoechenberger]

use type hints to specify "returns same type as self". Hopefully this will work (and not, e.g., say that it returns the Mixin class!) Curious what others think about this possible solution

Yep, this works. It's a bit clumsy until PEP 673 gets implemented with Python 3.11, but it's possible today:

# typing-test.py
from typing import TypeVar

MixinT = TypeVar("MixinT", bound="Mixin")

class Mixin:
    def foo(
        self: MixinT
    ) -> MixinT:
        return self

class A(Mixin):
    pass

class B(A, Mixin):
    pass


a = A()
b = B()

reveal_type(a.foo())
reveal_type(b.foo())

❯ mypy typing-test.py
typing-test.py:22: note: Revealed type is "typing-test.A"
typing-test.py:23: note: Revealed type is "typing-test.B"
Success: no issues found in 1 source file

So this reveals the correct types! Question is if and how Sphinx can handle this!

[mmagnuski]

I like the changes how they are now, I'm not sure investing too much time in reducing the text overlap is really worth it. You can always go back to saying "self" instead of mentioning correct object type. ;D