René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Use the C domain roles consistently in the documentation","articleBody":"`: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).\r\n\r\n`:c:member:` is used 813 times for 202 names.\r\n\r\n`:c:data:` is used 265 times for 143 names:\r\n\u003cdetails\u003e\r\n\r\n```\r\n:c:data:`command`\r\n:c:data:`errno`\r\n:c:data:`immutable types \u003cPy_TPFLAGS_IMMUTABLETYPE\u003e`\r\n:c:data:`nb_long`\r\n:c:data:`nb_reserved`\r\n:c:data:`PyBool_Type`\r\n:c:data:`Py_buffer`\r\n:c:data:`Py_buffer.format`\r\n:c:data:`Py_buffer.itemsize`\r\n:c:data:`Py_BytesWarningFlag`\r\n:c:data:`PyCallIter_Type`\r\n:c:data:`PyCFunction`\r\n:c:data:`PyCMethod`\r\n:c:data:`PyContextToken_Type`\r\n:c:data:`PyContext_Type`\r\n:c:data:`PyContextVar_Type`\r\n:c:data:`PyDateTimeAPI`\r\n:c:data:`PyDateTime_Date`\r\n:c:data:`PyDateTime_DateTime`\r\n:c:data:`PyDateTime_DateTimeType`\r\n:c:data:`PyDateTime_DateType`\r\n:c:data:`PyDateTime_Delta`\r\n:c:data:`PyDateTime_DeltaType`\r\n:c:data:`PyDateTime_Time`\r\n:c:data:`PyDateTime_TimeType`\r\n:c:data:`PyDateTime_TimeZone_UTC`\r\n:c:data:`PyDateTime_TZInfoType`\r\n:c:data:`Py_Ellipsis`\r\n:c:data:`Py_eval_input`\r\n:c:data:`PyExc_ArithmeticError`\r\n:c:data:`PyExc_AssertionError`\r\n:c:data:`PyExc_AttributeError`\r\n:c:data:`PyExc_BaseException`\r\n:c:data:`PyExc_BlockingIOError`\r\n:c:data:`PyExc_BrokenPipeError`\r\n:c:data:`PyExc_BufferError`\r\n:c:data:`PyExc_BytesWarning`\r\n:c:data:`PyExc_ChildProcessError`\r\n:c:data:`PyExc_ConnectionAbortedError`\r\n:c:data:`PyExc_ConnectionError`\r\n:c:data:`PyExc_ConnectionRefusedError`\r\n:c:data:`PyExc_ConnectionResetError`\r\n:c:data:`PyExc_DeprecationWarning`\r\n:c:data:`PyExc_EnvironmentError`\r\n:c:data:`PyExc_EOFError`\r\n:c:data:`PyExc_Exception`\r\n:c:data:`PyExc_FileExistsError`\r\n:c:data:`PyExc_FileNotFoundError`\r\n:c:data:`PyExc_FloatingPointError`\r\n:c:data:`PyExc_FutureWarning`\r\n:c:data:`PyExc_GeneratorExit`\r\n:c:data:`PyExc_ImportError`\r\n:c:data:`PyExc_ImportWarning`\r\n:c:data:`PyExc_IndentationError`\r\n:c:data:`PyExc_IndexError`\r\n:c:data:`PyExc_InterruptedError`\r\n:c:data:`PyExc_IOError`\r\n:c:data:`PyExc_IsADirectoryError`\r\n:c:data:`PyExc_KeyboardInterrupt`\r\n:c:data:`PyExc_KeyError`\r\n:c:data:`PyExc_LookupError`\r\n:c:data:`PyExc_MemoryError`\r\n:c:data:`PyExc_ModuleNotFoundError`\r\n:c:data:`PyExc_NameError`\r\n:c:data:`PyExc_NotADirectoryError`\r\n:c:data:`PyExc_NotImplementedError`\r\n:c:data:`PyExc_OSError`\r\n:c:data:`PyExc_OverflowError`\r\n:c:data:`PyExc_PendingDeprecationWarning`\r\n:c:data:`PyExc_PermissionError`\r\n:c:data:`PyExc_ProcessLookupError`\r\n:c:data:`PyExc_RecursionError`\r\n:c:data:`PyExc_ReferenceError`\r\n:c:data:`PyExc_ResourceWarning`\r\n:c:data:`PyExc_RuntimeError`\r\n:c:data:`PyExc_RuntimeWarning`\r\n:c:data:`PyExc_StopAsyncIteration`\r\n:c:data:`PyExc_StopIteration`\r\n:c:data:`PyExc_SyntaxError`\r\n:c:data:`PyExc_SyntaxWarning`\r\n:c:data:`PyExc_SystemError`\r\n:c:data:`PyExc_SystemExit`\r\n:c:data:`PyExc_TabError`\r\n:c:data:`PyExc_TimeoutError`\r\n:c:data:`PyExc_TypeError`\r\n:c:data:`PyExc_UnboundLocalError`\r\n:c:data:`PyExc_UnicodeDecodeError`\r\n:c:data:`PyExc_UnicodeEncodeError`\r\n:c:data:`PyExc_UnicodeError`\r\n:c:data:`PyExc_UnicodeTranslateError`\r\n:c:data:`PyExc_UnicodeWarning`\r\n:c:data:`PyExc_UserWarning`\r\n:c:data:`PyExc_ValueError`\r\n:c:data:`PyExc_Warning`\r\n:c:data:`PyExc_WindowsError`\r\n:c:data:`PyExc_ZeroDivisionError`\r\n:c:data:`Py_False`\r\n:c:data:`Py_file_input`\r\n:c:data:`Py_FileSystemDefaultEncodeErrors`\r\n:c:data:`PyFunction_Type`\r\n:c:data:`Py_IgnoreEnvironmentFlag`\r\n:c:data:`PyImport_FrozenModules`\r\n:c:data:`PyImport_Inittab`\r\n:c:data:`PyInstanceMethod_Type`\r\n:c:data:`PyMethod_Type`\r\n:c:data:`Py_mod_exec`\r\n:c:data:`PyModuleDef_HEAD_INIT`\r\n:c:data:`PyModule_Type`\r\n:c:data:`Py_None`\r\n:c:data:`Py_NotImplemented`\r\n:c:data:`PyOS_ReadlineFunctionPointer`\r\n:c:data:`Py_Py3kWarningFlag`\r\n:c:data:`PySeqIter_Type`\r\n:c:data:`Py_single_input`\r\n:c:data:`PyStructSequence_UnnamedField`\r\n:c:data:`Py_tp_base`\r\n:c:data:`Py_tp_bases`\r\n:c:data:`PyTrace_CALL`\r\n:c:data:`PyTrace_C_CALL`\r\n:c:data:`PyTrace_C_EXCEPTION`\r\n:c:data:`PyTrace_C_RETURN`\r\n:c:data:`PyTrace_EXCEPTION`\r\n:c:data:`PyTrace_LINE`\r\n:c:data:`PyTrace_OPCODE`\r\n:c:data:`PyTrace_RETURN`\r\n:c:data:`Py_True`\r\n:c:data:`PyType_GetModuleByDef`\r\n:c:data:`PyType_Type`\r\n:c:data:`PyUnicode_1BYTE_KIND`\r\n:c:data:`PyUnicode_2BYTE_KIND`\r\n:c:data:`PyUnicode_4BYTE_KIND`\r\n:c:data:`PyUnicode_WCHAR_KIND`\r\n:c:data:`Py_UTF8Mode`\r\n:c:data:`Py_Version`\r\n:c:data:`rl_attempted_completion_function`\r\n:c:data:`rl_completer_word_break_characters`\r\n:c:data:`rl_completion_display_matches_hook`\r\n:c:data:`rl_completion_type`\r\n:c:data:`rl_line_buffer`\r\n:c:data:`rl_pre_input_hook`\r\n:c:data:`rl_startup_hook`\r\n:c:data:`SpamError`\r\n:c:data:`sts`\r\n```\r\n\u003c/details\u003e\r\nIn some of these cases (e.g. for `nb_long` or `Py_buffer.format`) `:c:member:` looks more semantically appropriate.\r\n\r\n`:c:var:` is used 51 times for 28 names:\r\n\u003cdetails\u003e\r\n\r\n```\r\n:c:var:`Py_BytesWarningFlag`\r\n:c:var:`Py_DebugFlag`\r\n:c:var:`Py_DontWriteBytecodeFlag`\r\n:c:var:`Py_FileSystemDefaultEncodeErrors`\r\n:c:var:`Py_FileSystemDefaultEncoding`\r\n:c:var:`Py_FrozenFlag`\r\n:c:var:`Py_HasFileSystemDefaultEncoding`\r\n:c:var:`Py_HashRandomizationFlag`\r\n:c:var:`Py_IgnoreEnvironmentFlag`\r\n:c:var:`Py_InspectFlag`\r\n:c:var:`Py_InteractiveFlag`\r\n:c:var:`Py_IsolatedFlag`\r\n:c:var:`Py_LegacyWindowsFSEncodingFlag`\r\n:c:var:`Py_LegacyWindowsStdioFlag`\r\n:c:var:`Py_NoSiteFlag`\r\n:c:var:`Py_NoUserSiteDirectory`\r\n:c:var:`Py_OptimizeFlag`\r\n:c:var:`PyOS_InputHook`\r\n:c:var:`PyOS_ReadlineFunctionPointer`\r\n:c:var:`Py_QuietFlag`\r\n:c:var:`PyStructSequence_UnnamedField`\r\n:c:var:`PyType_Type`\r\n:c:var:`Py_UnbufferedStdioFlag`\r\n:c:var:`Py_UTF8Mode`\r\n:c:var:`Py_VerboseFlag`\r\n:c:var:`Py_Version`\r\n```\r\n\u003c/details\u003e\r\n\r\nIn some cases `:data:` (purposed for use with Python names) is used with a C name. It is definitely error.\r\n\r\nIn 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.\r\n\r\n\r\n\u003c!-- gh-linked-prs --\u003e\r\n### Linked PRs\r\n* gh-107092\r\n* gh-107113\r\n* gh-107121\r\n* gh-107129\r\n* gh-107138\r\n* gh-107063\n* gh-107310\n* gh-107311\n* gh-107312\n* gh-107313\n* gh-107318\n* gh-107330\n* gh-107331\n* gh-107378\n* gh-107379\n* gh-107384\n* gh-107385\n* gh-107416\n* gh-107417\n\u003c!-- /gh-linked-prs --\u003e\r\n","author":{"url":"https://github.com/serhiy-storchaka","@type":"Person","name":"serhiy-storchaka"},"datePublished":"2023-07-23T06:21:01.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":3},"url":"https://github.com/107091/cpython/issues/107091"}