Skip to content

Fix docs/API drift: descriptor_data and parse_characteristics batch flow #196

Description

@RonanB96

Library gap

Documentation and types suggest descriptor bytes can feed batch parsing, but the public API does not accept descriptor_data and nothing populates CharacteristicContext.descriptors.

Evidence (citations)

Docs claim to_parse_inputs produces input for parse_characteristics(..., descriptor_data=...):

  • docs/source/how-to/usage.md lines ~284–321 — builds descriptor_data then calls parse_characteristics(char_data) without passing it
  • src/bluetooth_sig/types/io.pyto_parse_inputs() docstring references parse_characteristics(char_data, descriptor_data=...)

Actual translator signature:

  • src/bluetooth_sig/core/translator.pyparse_characteristics(char_data, ctx=None) only
  • src/bluetooth_sig/core/parser.py_build_parse_context() does not preserve ctx.descriptors

Architecture docs describe descriptor validation path that is not wired:

  • docs/source/explanation/architecture/internals.md — “Descriptor Access Pattern”

Suggested approach (pick one direction — document decision in PR)

Option A (minimal): Fix docs to state descriptors are optional/manual; show read_descriptor() separately; remove false descriptor_data= API references.

Option B (small API): Add optional descriptor_data: dict[str, dict[str, bytes]] | None to batch parse, parse descriptors into CharacteristicContext.descriptors per char UUID — only if product owner wants validation enrichment (see issue #195 scope split).

This issue should at minimum eliminate doc/API contradiction. Implementation of full wiring can be a follow-up.

Acceptance criteria

  • No doc examples reference non-existent descriptor_data= parameter unless implemented
  • docs/source/how-to/migration.md checked for same drift
  • If Option B chosen: tests prove Valid Range affects validation when descriptor bytes supplied
  • Docs build / code-block tests pass if applicable

Key files

  • docs/source/how-to/usage.md
  • docs/source/how-to/migration.md
  • src/bluetooth_sig/types/io.py
  • src/bluetooth_sig/core/translator.py

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions