Repository navigation
docs: link library-internal references written as literals, and document the public classes missing from the inventory #1940
Description
Library-internal names in rendered prose are written as double-backtick literals, so they never link. Two examples: AppType.get at registry-protocol.rst:542, and FrameType.Flags at registry-protocol.rst:403. An audit of origin/main at 3c67a3890 checked every literal against the pinned build's objects.inv, excluding the changelog files:
- About 278 literals resolve to exactly one documented object. They are in docstrings,
#:comments, API pages and contributing pages. - About 183 are ambiguous. Causes include const/vendor twins, namesakes across
protocols/data/schema, and generic names such asFlagsorOption. Each needs its context read: either an explicitpcapkit.…path, or leave it as a literal where the prose means a concept such as "IPv4" or a layer. - Some public classes have no inventory entry at all:
CommandType,ResponseKind,GroupingInformation,ConformanceRequirement,SettingsandOptionEnumField(withpost_process). Per the maintainer, they get documented entries.
Fix: convert each literal to the matching role, add the missing entries, keep private helpers as literals, and pin the result in tests/project. Older changelog pages stay as literals, because today's inventory can point a historical name at a different object. The 1.5.0 changelog is tracked separately.
Activity
JarryShaw commentedon Oct 19, 2026
For private helpers, if they are referenced in the public docstrings, I'd prefer to include them in the API docs as well so that there will be no missing piece from the documentations.
JarryShaw commentedon Oct 19, 2026
Will do. Any private helper that a public docstring or doc page references gets its own API entry, and the reference becomes a role. The audit found these as literals:
ARP._make_proto_resolve/_make_addr_resolve/_acnm,OSPF._make_id_numbers,Ethernet._make_mac_addr,PCAPNG._make_mac_addr,IPv6._read_ip_hextet,Header._read_protos,Extractor._owns_input/_note_eof_progress,EtherType._insert_range,esp._resolve/_CRYPTO,ngap._convert/_revert/_PYCRATE/_PDU_LOCK,protocol._declared_keywords, andOptionEnumField.post_process. #1928 had turned the last two into literals; this PR documents and links them instead. Helpers that no rendered text names stay undocumented.docs: link the ipv6_ext page's next-layer lookup and drop timed test …
docs(const): link the remaining internal references in the AppType an…