Migrate ED-102B reference citations in decoding source comments/Javadoc

[willi-werner]

Summary

This PR migrates javadoc and code comment citations across the production decoding source (src/main/java/de/serosystems/lib1090/**, plus one test-file comment) to reference the integrated ED-102B standard (MOPS for 1090 MHz Extended Squitter ADS-B and TIS-B, bundling Change 1 and Change 2), replacing outdated DO-260B-era table/section references where they described content that has since been renumbered or reorganized.

• Base commit: 292329b84cef56720d827f1661d33dd3f9aaedc6 (v5)
• 101 files changed, comment and Javadoc only — no decoding logic was changed (verified: every added line is a comment/Javadoc line or blank)
• References to ICAO Annex 10, DO-185, and ED-129B were intentionally left untouched, as they are out of scope for this migration
• DO-260/DO-260B/DO-260C citations that describe historical provenance (e.g. "originally specified in DO-260", version-history framing) were left as-is; only citations functioning as normative "the standard requires X" references were updated
• Where a DO-260B table/section was renumbered in ED-102B (content matched by what the code actually does, never by number alone), the citation now points at the correct current table/section (e.g. DO-260B Table 2-65 → ED-102B TABLE 2-58 for SDA encoding; DO-260B Table N-7 → ED-102B TABLE N-9/2-68 depending on context; DO-260B Table 2-14 → ED-102B TABLE 2-67 for NIC/HCR)

Verification

All ~408 candidate citation sites (grep-derived, git-tracked source at the pinned base commit) were individually re-verified against the actual ED-102B full text this run, each recording a verdict (fixed / not-applicable / superseded) with its section/table citation and reasoning in migration_checklist.md. This supersedes the earlier, partially-unverified state of this branch.

Test plan

• Diff scope verified: only src/main/java/de/serosystems/lib1090/** and one test-file comment changed
• Diff content verified: every changed/added line falls within a comment/Javadoc block; no logic lines were modified
• mvn -o compile succeeds on the merged branch
• Citation accuracy: full re-verification against ED-102B section/table numbers is complete for all identified candidate sites

[mrksngl]

First note that I squash all those commits with merges into a single commit, so pull the current docs/ed102b-reference-migration branch with a hard reset.

Then rework references:

• use a consistent citation style: the standard, then a space, then character §, then the paragraph. Example ED-102B §2.2.3
• when referencing tables, use style "ED-102B §... TABLE X-..."
• when referencing figures, use style "ED-102B §... Figure X-..."
• don't typeset paragraphs or references in parenthesis
• do not explicitly mention EUROCAE in sources
• In javadoc, especially on UnspecifiedFormatError, always add the reference to the corresponding table (or just paragraph if there is no table)
• beware that some messages are no longer specified in ED-102B, i.e. that were deprecated. In that case, the corresponding former standard shall be referenced.
• some messages (especially outside ads-b/ads-r/tis-b) are not specified by ED-102B. For example, ShortACAS is defined in Annex 10 Volume 4.
• also, in class de.serosystems.lib1090.decoding.Identification, keep the former reference to ED-102B §2.2.7.1 which is on backwards compatibility of the version.

[willi-werner]

Update on the ED-102B reference migration, following the review comment above.

Where the branch stands. docs/ed102b-reference-migration is currently 248 commits ahead of v5 (147 files changed), tip 71e5504. Every substantive change is comments, Javadoc, or exception-message text — no decoding logic was touched.

Style rules from the review — current state of the tree:

• No literal "EUROCAE" anywhere in src/ (was present in several files).
• No lower-case Table references; all are TABLE X-N.
• No upper-case FIGURE; all are Figure X-N (this class of fix briefly regressed at five newly-grounded call sites and has since been corrected back to zero).
• The malformed table reference in ADSBReceiverVersionMsg (a paragraph number sitting in a table slot) has been corrected.

Grounding gaps closed since the last update, each against the actual standard text rather than by pattern-matching the existing citation style:

• The eight Comm-B/GICB register classes now carry page-level ICAO Doc 9871 references, and the base register class's TABLE A-1 citation was re-verified.
• The historical DO-260B paragraphs for the velocity-uncertainty field and for target-state Subtypes 3 and 4 are now cited.
• ED-102B §2.2.19 ("Traffic Uplink Management Message") was walked in full to ground the Mode A code, intent-change, and MLAT system-status messages, including the exact TYPE=28 subtype for each.
• The military DF=19 format now cites a second source (ICAO Doc 9871) alongside Annex 10 Volume IV.
• The ED-102B table number for the 6-bit callsign alphabet is now cited.
• The table-of-contents-vs-body discrepancy over the position-accuracy/integrity table number is resolved: both TABLE 2-68 (NACP) and TABLE 2-70 (SIL) are real, distinct tables, and the affected classes now cite whichever one they actually use.
• Page-level references were added for the surface-position base format, the weather-report alternate-state figure, and the high-vertical-accuracy position/velocity figures.
• UASRPASContingencyMsg and CASOperationalCoordinationMsg — the two classes that had no citation at all — now carry class-level ED-102B citations (including the standard's own note that neither message is permitted for broadcast).

One honest correction to flag. The Identification class's ED-102B §2.2.7.1 citation (backwards compatibility of the ADS-B version number) is intact on the branch, but it did not simply survive untouched: the original migration had actually removed it in favor of a different (incorrect) Appendix N reference, and it had to be restored from scratch, which means its wording is not byte-for-byte what was on the branch before the migration started, even though the citation itself is correct.

Still open. Six sites embed a full citation inside an explanatory parenthetical clause rather than a bare "standard §paragraph" (ModeACodeMsg, ModeACodeV1Msg, MLATSystemStatusMsg ×2, IntentChangeMsg ×2) — these are being worked and aren't part of the question below.

A question for you. Separately from those six, there are 25 places across 10 classes where a citation is immediately followed by a short parenthetical gloss that disambiguates which of two or more sibling paragraphs/subtypes/versions it points to — for example "ED-102B §2.2.3.2.6.1.7 (subsonic) resp. §2.2.3.2.6.2.7 (supersonic)" or "§N.2.2.4 (version 0) resp. §N.3.2.4 (version 1)". These weren't touched, since your review comment's parentheses rule was read as targeting citations typeset in parentheses, not a short qualifier trailing one. They are:

• PositionMsg.java:25-26 — (airborne position) / (surface position)
• PositionMsgWithTime.java:24,34 — (version 0) / (version 1)
• WxAIREPWeatherMsg.java:30 — (alternate weather state, same encoding)
• TargetStateAndStatusMsg.java:68 — (sign) / (magnitude)
• VelocityOverGroundMsg.java:80-81, 86-87, 92-93, 99 — four (subsonic) / (supersonic) pairs
• AirborneVelocityMsg.java:40-41 — (subsonic) / (supersonic)
• AirspeedHeadingMsg.java:27-28, 36, 58, 65, 81 — five (subsonic) / (supersonic) or (subtype=N, ...) pairs
• IntentChangeMsg.java:24-25 — (Subtype=1) … (Subtype=4)
• ExtendedSquitter.java:30 — (DF=17) / (DF=18) / (DF=19)
• L0Latitude.java:145 — (NL Function Reference Table)

Is this kind of short disambiguating gloss acceptable to keep, or would you rather it were removed everywhere (e.g. rewritten as separate sentences or @see references)? I'd rather get one ruling and apply it consistently than guess and have to redo it. This is recorded as an explicitly open item; I'm not blocking further work on your answer.

migration_checklist.md on the branch has the line-level citation verdicts referenced above, including document + section/table/figure re-verification against the source standards (ED-102B, ICAO Annex 10 Volume IV, ICAO Doc 9871, DO-260B).

The branch stays open and assigned to you as before — no merge or review request from this end.

[willi-werner]

Follow-up on two citation-accuracy items from the ongoing documentation-only migration in this branch, both re-verified against the standard text this pass:

1. Type-code field table locus (ExtendedSquitter). The type-code (TC) field citation is being corrected from ED-102B Table 2-14 to TABLE 2-9. Table 2-14 is "Status Bit for Heading/Ground Track" Encoding — an unrelated encoding table. TABLE 2-9, "Determining ADS-B Message Type", is the table that actually maps DF=17 (or DF=18 with CF=0/1/6) message content to ADS-B message type, which is what the TC field decode needs.

2. Why ED-102B §2.2.19 was rejected as a citation for the Mode A code / intent-change / MLAT-status messages. §2.2.19 is the Traffic Uplink Management Message: a DF=18/CF=4 broadcast in which a ground station tells clients whether TIS-B, ADS-R and ADS-SLR services are being provided, carried in a 5-bit management-message bit field. It is not type-coded and has no relationship to the Mode A code, intent-change, or MLAT system-status messages it had been considered for, so it was dropped as a candidate reference for those classes.

Both are comment/citation corrections only — no decoding logic is touched by either change.

[willi-werner]

Following up on the citation-prefix inconsistency flagged for this migration: fixed the redundant ED-102B Appendix <letter> §<letter>... prefixing.

Decision: when a citation's paragraph locus already starts with the appendix letter (e.g. §N.3.3.1), the citation should not additionally carry a preceding Appendix <letter> (or Annex <letter>) phrase — that phrase is redundant. So ED-102B Appendix N §N.3.3.1 becomes ED-102B §N.3.3.1.

Why: verified directly against the standard's own text — Appendix N's paragraph numbering (N.1, N.1.1, N.2.2.2, N.3.3.1, ...) never restates "Appendix N" at the paragraph level; the leading N. component is already self-identifying (the appendix itself is titled/paginated "Appendix N" / "Page N-x" in its header, and its own table-of-contents summary only uses the bare word "Appendix N" to describe the appendix as a whole, not to prefix a specific paragraph citation). This rule applies only to lettered-appendix locus numbers (A.x, N.x, T.x, ...) — numeric-leading loci (e.g. §2.2.3.2.2) are untouched, since a numeric locus doesn't self-identify an appendix/annex.

Scope: 46 occurrences across 19 files under src/main/java, all of the ED-102B Appendix N §N.... form (no Appendix A/Appendix T/Annex <letter> variants were present in the tree). Comment/Javadoc/exception-message text only — no decoding logic touched. Full file/line list is recorded in the project's citation-prefix decision note.

No new reviewer action needed — this is a documentation-only normalization consistent with the migration's existing per-class commit convention.

[willi-werner]

Follow-up on one more citation-scope question from the ongoing documentation-only migration: whether the four explanatory notes removed from IntentChangeMsg.java, MLATSystemStatusMsg.java, ModeACodeV1Msg.java, and msgs/squitter/ModeACodeMsg.java (each explaining why ED-102B §2.2.19 did not apply to that class) should stay removed or be restored in short form.

Decision: restore short, factual versions of all four. Re-reading ED-102B §2.2.19 confirms it defines the "Traffic Uplink Management Message" — a distinct DF=18/CF=4 ground-to-client broadcast conveying TIS-B/ADS-R/ADS-SLR service-status data, unrelated in subject to the Mode A code, intent-change, and MLAT-status fields these four classes decode. On that basis the four notes are genuine, factual citation disambiguation (naming a specific standard section and stating why it doesn't apply), not narration about the migration's own process, so they read the same as any other "not to be confused with X" citation note and belong back in the Javadoc — unlike the one note the reviewer asked to drop in Identification.java, which was commentary on the authoring process itself rather than a disambiguation grounded in the standard's own section content.

Consequence for the branch: each of the four files gets its own small restoration commit (one class per commit, matching this migration's existing convention), re-adding the note verbatim at the point it was removed. No decoding logic is touched by any of these changes — comment/citation content only.

[willi-werner]

Consolidating the two follow-ups posted earlier today (this comment supersedes repeating either point a third time) with the remaining ledger items, all re-checked against the branch tip at post time (36c08c8b, 436 commits ahead of v5):

1. Wrong-table citation fixes (both already detailed in the first follow-up above).

• ExtendedSquitter type-code/subtype field: corrected from Table 2-14 to ED-102B §2.2.3.2.2 TABLE 2-9 ("Determining ADS-B Message Type") — 053663c.
• ModeSDownlinkMsg and QualifiedAddress CF field: corrected from Table 2-9 to ED-102B §2.2.3.2.1.3 TABLE 2-7 ("CF Field Code Definitions") — 0e600d5 (ModeSDownlinkMsg) and b8318e3 (QualifiedAddress).

2. Table-casing restoration. All table citations under src/main/java are back to uppercase TABLE X-N (b98853e); a fresh scan of the tree at the current tip finds zero lowercase Table N-N occurrences.

3. Aside-restoration decision (second follow-up above, now landed). The four §2.2.19 citation-disambiguation notes are restored, one class per commit: IntentChangeMsg (f369a12), MLATSystemStatusMsg (6da2a5a), ModeACodeV1Msg (175f8e2), and squitter/ModeACodeMsg (36c08c8). Each states, in short factual form, why ED-102B §2.2.19 ("Traffic Uplink Management Message", a DF=18/CF=4 ground-to-client service-status broadcast) doesn't apply to that class's field — that's disambiguation grounded in the standard's own section content, not process narration, so it's kept. This is distinct from Identification.java's reviewer-named line, which stays removed since it was commentary on the authoring process rather than standard content.

4. Internal checklist file. migration_checklist.md is confirmed absent at the current tip (git show 36c08c8b:migration_checklist.md → path does not exist); its removal (69eb5f2) is the tip-side commit for that item.

5. Appendix-letter citation prefix (third follow-up above). Redundant ED-102B Appendix N §N.... prefixes were dropped wherever the paragraph locus's own leading letter already identifies the appendix (4d5f165, 46 occurrences across 19 files) — e.g. ED-102B Appendix N §N.3.3.1 → ED-102B §N.3.3.1. Rule applies only to lettered-appendix loci (A.x, N.x, T.x, ...); numeric loci such as §2.2.3.2.2 are untouched, since a numeric locus doesn't self-identify an appendix/annex. A fresh scan of the current tip finds zero remaining occurrences of that redundant pattern.

6. Commit convention. Every item above landed as its own small, per-class (or clearly single-purpose) commit — no squashing, no bundling — consistent with the migration's existing convention. The branch is currently 436 commits ahead of v5.

No new reviewer action is required for any of the above; all changes are comment/Javadoc/exception-message text only, no decoding logic touched.

[mrksngl]

Reworked changes, lgtm now