I just wanted to use Raw.add_channels(), so I looked at the API docs and even though I'm a developer, it actually took me a couple of seconds to even understand what could probably be meant, and still I think I'll have to take a look at the code to get a better understanding:

• What is self
• What is meant by, "Must contain the same type as the current object" (actually I'm still unsure, I'll probably have to look at the code to figure it out)
• "force the info objects ... to match the values in self". I have absolutely no clue what that means.
• Why does it say it can return Raw, Evoked, or Epochs – I was looking it up for Raw at https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.add_channels, and I don't think my Raw is suddenly gonna get turned into an Epoch by this method, no?

I believe we're making bad use of the docdict here, avoiding redundancy but making the docs effectively useless because they're too weird and hard to understand.

Didn't we recently have a somewhat similar case where we ended up with a way to improve things?