Use the C domain roles consistently in the documentation#107091
Description
: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:
Details
: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` :c:var: is used 51 times for 28 names:
Details
: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