Repository navigation
docs(conventions): settle the member-order page wording #2765 left open #2772
Description
What
#2765 (closing #2490) applied rule c, subgroup d and registry-map order, using my recommendations on five wording questions that protocol-member-order.rst leaves open. #2490 closed before they were ruled on, so they move here with needs: decision.
- Several registries in one class: list all readers before all makers (the MH/PCAPNG shape)? Rec: yes; the guard checks only within each registry.
PCAPNG.__option__order: namespace then value, or byopt_value? Rec: namespace then value, written on the page.- Int keys with no enum: change "alphabetically" to "by key value", which is what TCP/UDP/FRAD now do? Rec: yes. This is the one place where the page and the code currently disagree.
- PCAP-NG
Option.__enum__: in scope? Rec: out of scope, sinceOption.register's warning relies on its order. .rstmember lists (e.g. IPv4's) no longer follow source order. Rec: realign them in this issue's docs-only PR.
Activity
JarryShaw commentedon Nov 4, 2026
JarryShaw commentedon Nov 4, 2026
Reconciled. On 1, 2, 3 and 5 you took the recommendations. On 4, yes: it can be brought in scope.
PCAPNG.__option__: ordered by namespace, then by value. That order is written on the page.Option.__enum__: today its order matters only becauseOption.register's clash warning names the clashing namespaces in map order. Make that warning list them in a fixed order of its own, and the map can then follow the page like the rest. The guard gains a check for it..rstmember lists (IPv4's and the others): realigned to source order.A worker is starting now. The
Option.registerchange touches code, so this goes as a PR rather than a docs-only push.JarryShaw commentedon Nov 4, 2026
what needs my decision?
JarryShaw commentedon Nov 4, 2026
Four small choices on #2779, the PR for this issue. The PR already follows my recommendation on each, so a ruling only adjusts it:
PCAPNG.__option__. (a) KeepOptionType's declared order, which is the map as it stands, withoptfirst. (b) Go alphabetical. Rec: (a).Protocoldocs page. It documents members thatProtocolBasedefines, so I left its order alone. (a) Leave it. (b) Realign it toProtocolBase's source order. Rec: (a)..rstmember order. Nothing yet checks that the pages stay in source order. (a) Add one as a follow-up. (b) Don't. Rec: (a).A reply such as "take all recommendations" here or on #2779 settles it.
JarryShaw commentedon Nov 4, 2026
take all recommendations
JarryShaw commentedon Nov 4, 2026
Reconciled: all four recommendations stand. #2779 needs no change.
PCAPNG.__option__keepsOptionType's namespace order.Protocoldocs page keeps its order..rstmember lists in source order goes in a follow-up issue, filed now. It is test-only, so it can land straight on main once docs(conventions): settle the member-order page wording and align the protocol registry with the other maps (#2772, #2773) #2779 merges.Once its cross-review and CI finish, #2779 closes this issue.
docs(conventions): settle the member-order page wording and align the…
test(project): guard that protocol docs pages list members in class s…