[RFC] changing python type by a term definition in docstring

In the following docstring instead of using the python type as description, could we use a glossary term instead?

https://github.com/mne-tools/mne-python/blob/adb70865accfbf2e473d0f78e5be69c090581c0d/mne/io/meas_info.py#L205-L207

Or maybe we should keep the python type and link the term in the description.

    dig : list of dict | None
        The Polhemus :term:`digitization` data in head coordinates.
        See Notes for more information.

WDYT?

cc: @drammock, @larsoner, @agramfort

Maybe something like this could work:

numpydoc_xref_aliases = {
    'Popen': 'python:subprocess.Popen',
    'file-like': ':term:`file-like <python:file object>`',
    ...
    # MNE
    'Label': 'mne.Label', 'Forward': 'mne.Forward', 'Evoked': 'mne.Evoked',
    ...
    'Transform': 'mne.transforms.Transform',
    # MNE-terms
    'digitization': ':term:`digitization`',
}

Suggested term

digitization (abbr. dig) digpoint

Suggested definition

digitization: list of digpoints digpoint: Dictionary contaning ~Polhemus~ digitization data (kind, identifier, position, and coord_frame)

@drammock feel free to rephrase the whole thing 😉 (or push me to do it)

[agramfort]

sounds good !

+1 to add a “digitization” entry in glossary

in the place you point to we should not mention Polhemus. it’s not the only system to get a valid digitization.

[larsoner]

Whoops I mean #6461