Skip to content

Document Feature and RelationMember fields in feature.proto - #632

Merged
brawer merged 1 commit into
mainfrom
document-feature-proto-fields
Aug 12, 2026
Merged

Document Feature and RelationMember fields in feature.proto#632
brawer merged 1 commit into
mainfrom
document-feature-proto-fields

Conversation

@brawer

@brawer brawer commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

What

Comment-only change: documents every field of Feature and RelationMember in feature.proto. Prompted by reviewing doc clarity after #631 landed centroid_s2_cell_id/coverage_s2_cell_id on FeatureToIndex — that message ended up well-documented, but Feature/RelationMember had real gaps.

Gaps fixed

  • tags: gave no clue it's flattened (key_id, value_id) StringPool-index pairs. That fact only existed in a private helper's rustdoc in assemble.rs, invisible from the proto itself.
  • way_members vs RelationMember.id: both uint64, one message apart, look parallel — but way_members holds raw OSM node IDs while RelationMember.id holds id-encoded feature IDs (osm_id*10 + {1,2,3}). Nothing warned a reader they're differently encoded.
  • RelationMember.role: no comment at all — not obviously a StringPool index rather than an enum or the literal role string.
  • version/changeset/timestamp: undocumented, no units, no note that they default to 0 when OSM doesn't supply them.
  • geometry_wkb: didn't say it's little-endian WKB with (longitude, latitude) coordinate order.
  • No message-level note on which fields apply to which OSM element kind (way_members ways-only, relation_members relations-only).

Also gave Feature the same "internal/ephemeral, never sent over the wire or stored long-term, field numbers are free to be renumbered" note FeatureToIndex already had. Since Feature is declared first in the file, the full explanation lives there and FeatureToIndex just refers back to it, so a top-to-bottom reader gets the full story once, in the right order.

Fixed two pre-existing typos in FeatureToIndex's trailing comment (should'tshouldn't, finalmfinal) while in the area.

All field semantics were checked against the actual population code (assemble_tags, assemble_relation_members, assemble_feature in assemble.rs), not guessed.

Testing

cargo build (regenerates the prost bindings from the proto) and cargo fmt --check: clean. No .rs changes, so no behavior change.

🤖 Generated with Claude Code

FeatureToIndex was well-documented after the centroid_s2_cell_id change,
but Feature and RelationMember had real gaps for a newcomer:

- `tags` gave no clue it's flattened (key_id, value_id) StringPool-index
  pairs; that fact was only written down in a private helper's rustdoc
  in assemble.rs, invisible from the proto itself.
- `way_members` and `RelationMember.id` look parallel (both uint64,
  one message apart) but use different ID encodings: way_members holds
  raw OSM node IDs, RelationMember.id holds `id`-encoded feature IDs.
  Nothing warned a reader of that.
- `RelationMember.role` had no comment at all -- not obviously a
  StringPool index rather than an enum or literal role string.
- version/changeset/timestamp were undocumented: no units, no note
  that they default to 0 when OSM doesn't supply them.
- geometry_wkb didn't say it's little-endian WKB with (lon, lat) order.
- No message-level note on which fields apply to which OSM element kind.

Also gave Feature the same "this is internal/ephemeral, never sent over
the wire or stored long-term, field numbers are free to be renumbered"
note FeatureToIndex already had -- and, since Feature is declared first,
moved the full explanation there and had FeatureToIndex just refer back
to it, so a top-to-bottom reader sees the full story once, in order.

Fixed two pre-existing typos in FeatureToIndex's trailing comment
("should't" -> "shouldn't", "finalm" -> "final") while in the area.

Comment-only change; no behavior change.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

@brawer brawer left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@brawer
brawer added this pull request to the merge queue Aug 12, 2026
Merged via the queue into main with commit 46d9a92 Aug 12, 2026
4 checks passed
@brawer
brawer deleted the document-feature-proto-fields branch August 12, 2026 07:59
@brawer brawer added the documentation Improvements or additions to documentation label Aug 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant