Use the C domain roles consistently in the documentation

[serhiy-storchaka]

:c:member:, :c:data: and :c:var: are equivalent. I do not know whether there is a semantic difference between :c:data: and :c:var: (although I think that :c:member: is semantically different and should be used for attributes).

:c:member: is used 813 times for 202 names.

:c:data: is used 265 times for 143 names:

:c:data:`command`
:c:data:`errno`
:c:data:`immutable types <Py_TPFLAGS_IMMUTABLETYPE>`
:c:data:`nb_long`
:c:data:`nb_reserved`
:c:data:`PyBool_Type`
:c:data:`Py_buffer`
:c:data:`Py_buffer.format`
:c:data:`Py_buffer.itemsize`
:c:data:`Py_BytesWarningFlag`
:c:data:`PyCallIter_Type`
:c:data:`PyCFunction`
:c:data:`PyCMethod`
:c:data:`PyContextToken_Type`
:c:data:`PyContext_Type`
:c:data:`PyContextVar_Type`
:c:data:`PyDateTimeAPI`
:c:data:`PyDateTime_Date`
:c:data:`PyDateTime_DateTime`
:c:data:`PyDateTime_DateTimeType`
:c:data:`PyDateTime_DateType`
:c:data:`PyDateTime_Delta`
:c:data:`PyDateTime_DeltaType`
:c:data:`PyDateTime_Time`
:c:data:`PyDateTime_TimeType`
:c:data:`PyDateTime_TimeZone_UTC`
:c:data:`PyDateTime_TZInfoType`
:c:data:`Py_Ellipsis`
:c:data:`Py_eval_input`
:c:data:`PyExc_ArithmeticError`
:c:data:`PyExc_AssertionError`
:c:data:`PyExc_AttributeError`
:c:data:`PyExc_BaseException`
:c:data:`PyExc_BlockingIOError`
:c:data:`PyExc_BrokenPipeError`
:c:data:`PyExc_BufferError`
:c:data:`PyExc_BytesWarning`
:c:data:`PyExc_ChildProcessError`
:c:data:`PyExc_ConnectionAbortedError`
:c:data:`PyExc_ConnectionError`
:c:data:`PyExc_ConnectionRefusedError`
:c:data:`PyExc_ConnectionResetError`
:c:data:`PyExc_DeprecationWarning`
:c:data:`PyExc_EnvironmentError`
:c:data:`PyExc_EOFError`
:c:data:`PyExc_Exception`
:c:data:`PyExc_FileExistsError`
:c:data:`PyExc_FileNotFoundError`
:c:data:`PyExc_FloatingPointError`
:c:data:`PyExc_FutureWarning`
:c:data:`PyExc_GeneratorExit`
:c:data:`PyExc_ImportError`
:c:data:`PyExc_ImportWarning`
:c:data:`PyExc_IndentationError`
:c:data:`PyExc_IndexError`
:c:data:`PyExc_InterruptedError`
:c:data:`PyExc_IOError`
:c:data:`PyExc_IsADirectoryError`
:c:data:`PyExc_KeyboardInterrupt`
:c:data:`PyExc_KeyError`
:c:data:`PyExc_LookupError`
:c:data:`PyExc_MemoryError`
:c:data:`PyExc_ModuleNotFoundError`
:c:data:`PyExc_NameError`
:c:data:`PyExc_NotADirectoryError`
:c:data:`PyExc_NotImplementedError`
:c:data:`PyExc_OSError`
:c:data:`PyExc_OverflowError`
:c:data:`PyExc_PendingDeprecationWarning`
:c:data:`PyExc_PermissionError`
:c:data:`PyExc_ProcessLookupError`
:c:data:`PyExc_RecursionError`
:c:data:`PyExc_ReferenceError`
:c:data:`PyExc_ResourceWarning`
:c:data:`PyExc_RuntimeError`
:c:data:`PyExc_RuntimeWarning`
:c:data:`PyExc_StopAsyncIteration`
:c:data:`PyExc_StopIteration`
:c:data:`PyExc_SyntaxError`
:c:data:`PyExc_SyntaxWarning`
:c:data:`PyExc_SystemError`
:c:data:`PyExc_SystemExit`
:c:data:`PyExc_TabError`
:c:data:`PyExc_TimeoutError`
:c:data:`PyExc_TypeError`
:c:data:`PyExc_UnboundLocalError`
:c:data:`PyExc_UnicodeDecodeError`
:c:data:`PyExc_UnicodeEncodeError`
:c:data:`PyExc_UnicodeError`
:c:data:`PyExc_UnicodeTranslateError`
:c:data:`PyExc_UnicodeWarning`
:c:data:`PyExc_UserWarning`
:c:data:`PyExc_ValueError`
:c:data:`PyExc_Warning`
:c:data:`PyExc_WindowsError`
:c:data:`PyExc_ZeroDivisionError`
:c:data:`Py_False`
:c:data:`Py_file_input`
:c:data:`Py_FileSystemDefaultEncodeErrors`
:c:data:`PyFunction_Type`
:c:data:`Py_IgnoreEnvironmentFlag`
:c:data:`PyImport_FrozenModules`
:c:data:`PyImport_Inittab`
:c:data:`PyInstanceMethod_Type`
:c:data:`PyMethod_Type`
:c:data:`Py_mod_exec`
:c:data:`PyModuleDef_HEAD_INIT`
:c:data:`PyModule_Type`
:c:data:`Py_None`
:c:data:`Py_NotImplemented`
:c:data:`PyOS_ReadlineFunctionPointer`
:c:data:`Py_Py3kWarningFlag`
:c:data:`PySeqIter_Type`
:c:data:`Py_single_input`
:c:data:`PyStructSequence_UnnamedField`
:c:data:`Py_tp_base`
:c:data:`Py_tp_bases`
:c:data:`PyTrace_CALL`
:c:data:`PyTrace_C_CALL`
:c:data:`PyTrace_C_EXCEPTION`
:c:data:`PyTrace_C_RETURN`
:c:data:`PyTrace_EXCEPTION`
:c:data:`PyTrace_LINE`
:c:data:`PyTrace_OPCODE`
:c:data:`PyTrace_RETURN`
:c:data:`Py_True`
:c:data:`PyType_GetModuleByDef`
:c:data:`PyType_Type`
:c:data:`PyUnicode_1BYTE_KIND`
:c:data:`PyUnicode_2BYTE_KIND`
:c:data:`PyUnicode_4BYTE_KIND`
:c:data:`PyUnicode_WCHAR_KIND`
:c:data:`Py_UTF8Mode`
:c:data:`Py_Version`
:c:data:`rl_attempted_completion_function`
:c:data:`rl_completer_word_break_characters`
:c:data:`rl_completion_display_matches_hook`
:c:data:`rl_completion_type`
:c:data:`rl_line_buffer`
:c:data:`rl_pre_input_hook`
:c:data:`rl_startup_hook`
:c:data:`SpamError`
:c:data:`sts`

In some of these cases (e.g. for `nb_long` or `Py_buffer.format`) `:c:member:` looks more semantically appropriate.

:c:var: is used 51 times for 28 names:

:c:var:`Py_BytesWarningFlag`
:c:var:`Py_DebugFlag`
:c:var:`Py_DontWriteBytecodeFlag`
:c:var:`Py_FileSystemDefaultEncodeErrors`
:c:var:`Py_FileSystemDefaultEncoding`
:c:var:`Py_FrozenFlag`
:c:var:`Py_HasFileSystemDefaultEncoding`
:c:var:`Py_HashRandomizationFlag`
:c:var:`Py_IgnoreEnvironmentFlag`
:c:var:`Py_InspectFlag`
:c:var:`Py_InteractiveFlag`
:c:var:`Py_IsolatedFlag`
:c:var:`Py_LegacyWindowsFSEncodingFlag`
:c:var:`Py_LegacyWindowsStdioFlag`
:c:var:`Py_NoSiteFlag`
:c:var:`Py_NoUserSiteDirectory`
:c:var:`Py_OptimizeFlag`
:c:var:`PyOS_InputHook`
:c:var:`PyOS_ReadlineFunctionPointer`
:c:var:`Py_QuietFlag`
:c:var:`PyStructSequence_UnnamedField`
:c:var:`PyType_Type`
:c:var:`Py_UnbufferedStdioFlag`
:c:var:`Py_UTF8Mode`
:c:var:`Py_VerboseFlag`
:c:var:`Py_Version`

In some cases :data: (purposed for use with Python names) is used with a C name. It is definitely error.

In what cases should we use :c:data: and in what cases should we use :c:var:? I do not see a system in the current use.

Linked PRs

• gh-107091: Fix the use of some C domain roles #107092
• [3.12] gh-107091: Fix the use of some C domain roles (GH-107092) #107113
• [3.11] gh-107091: Fix the use of some C domain roles (GH-107092) #107121
• gh-107091: Fix some uses of :c:member: role #107129
• gh-107091: Fix some uses of :c:type: role #107138
• gh-107091: Use :c:var: consistently for Py_Version #107063
• [3.12] gh-107091: Fix some uses of :c:member: role (GH-107129) #107310
• [3.11] gh-107091: Fix some uses of :c:member: role (GH-107129) #107311
• [3.12] gh-107091: Fix some uses of :c:type: role (GH-107138) #107312
• [3.11] gh-107091: Fix some uses of :c:type: role (GH-107138) #107313
• gh-107091: Fix some uses of :attr: role #107318
• [3.12] gh-107091: Fix some uses of :attr: role (GH-107318) #107330
• [3.11] gh-107091: Fix some uses of :attr: role (GH-107318) #107331
• gh-107091: Fix some uses of :func: role #107378
• gh-107091: Fix some uses of :const: role #107379
• [3.12] gh-107091: Fix some uses of :const: role (GH-107379) #107384
• [3.11] gh-107091: Fix some uses of :const: role (GH-107379) #107385
• [3.12] gh-107091: Fix some uses of :func: role (GH-107378) #107416
• [3.11] gh-107091: Fix some uses of :func: role (GH-107378) #107417

[serhiy-storchaka]

Py_BytesWarningFlag, Py_FileSystemDefaultEncodeErrors, Py_IgnoreEnvironmentFlag, PyOS_ReadlineFunctionPointer, PyStructSequence_UnnamedField, PyType_Type, Py_UTF8Mode, Py_Version are used with both :c:data: and :c:var: roles.

[erlend-aasland]

In what cases should we use :c:data: and in what cases should we use :c:var:? I do not see a system in the current use.

The former is the most frequent used, so it would be less churn to change :c:var: to :c:data:.

[erlend-aasland]

Another option is to keep both :c:var: and c:data: and make sure they are referenced properly; that generates minimal churn.