Skip to content

docs: complete uORB and KVDB API documentation coverage#532

Merged
tanghao-xiaomi merged 1 commit intoopen-vela:devfrom
tanghao-xiaomi:refactor-uorb-kvdb-api
May 8, 2026
Merged

docs: complete uORB and KVDB API documentation coverage#532
tanghao-xiaomi merged 1 commit intoopen-vela:devfrom
tanghao-xiaomi:refactor-uorb-kvdb-api

Conversation

@tanghao-xiaomi
Copy link
Copy Markdown
Collaborator

Overview

Bring uorb.md and kvdb.md to 100% coverage of their public headers, filling in the APIs that were previously missing from the earlier pass.

Coverage

Module Header Before After
uORB apps/system/uorb/uORB/uORB.h 32 / 48 48 / 48
KVDB frameworks/system/utils/include/kvdb.h + cutils/properties.h 23 / 31 31 / 31

Main Changes

uorb.md

  • Added 18 core APIs that were previously missing: orb_advertise, orb_advertise_multi, orb_advertise_queue, orb_advertise_multi_queue, orb_advertise_multi_queue_persist_info, orb_publish, orb_publish_auto, orb_subscribe, orb_subscribe_wakeup, orb_subscribe_multi_wakeup, orb_copy, orb_unlink, orb_absolute_time, orb_set_interval, orb_get_interval, orb_set_frequency, orb_get_frequency, plus minor entries.
  • Fixed duplicate empty ## 发布接口 heading.
  • Corrected ### orb_scanf title to ### orb_sscanf (the signature inside the code block was already orb_sscanf; only the heading was inconsistent).

kvdb.md

  • Added property_list_binary (binary-value iteration).
  • Split four composite sections so each public API has its own ### name entry, per api-doc-standards.md:
    • property_get_bool/int32/int64_with_err → 3 entries
    • property_set_bool/int32/int64 → 3 entries
    • property_set_bool/int32/int64_oneway → 3 entries
    • property_set_buffer / property_set_buffer_oneway → 2 entries

Quality

  • Each new section includes a signature, a Chinese description, a **参数**: list, and a **返回值**: section.
  • Every referenced function name has been verified against the source headers.
  • Both files retain their existing openvela implementation notes and functional grouping.
  • No Doxygen or Sphinx directives remain.

Placement Rationale

Both files stay in framework/ (not kernel/) because:

  • uORB source lives in apps/system/uorb/, a userspace framework component, not nuttx/ kernel.
  • KVDB source lives in frameworks/system/utils/, also userspace.
  • This matches the rest of the framework-level API docs (bluetooth, media, telephony, feature, etc.) and the navigation in framework/index.md.

Statistics

2 files changed, +1156 / -262 lines.

@tanghao-xiaomi
Copy link
Copy Markdown
Collaborator Author

/check-cla

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 8, 2026

✅ CLA Verification Complete

@tanghao-xiaomi All contributors have signed the CLA!

  • zhangxiaowei16@xiaomi.com

📋 View detailed check results: Action Run #25548324325

Your pull request can now proceed with the review process! 🎉

Bring both uorb.md and kvdb.md to 100% coverage of their public headers
following the openvela API documentation standard.

uorb.md:
  - Add 18 previously missing core APIs, including orb_advertise,
    orb_advertise_multi, orb_advertise_queue, orb_advertise_multi_queue,
    orb_advertise_multi_queue_persist_info, orb_publish, orb_publish_auto,
    orb_subscribe, orb_subscribe_wakeup, orb_subscribe_multi_wakeup,
    orb_copy, orb_unlink, orb_absolute_time, orb_set_interval,
    orb_get_interval, orb_set_frequency, orb_get_frequency
  - Fix duplicate '## 发布接口' empty heading
  - Correct '### orb_scanf' title to '### orb_sscanf' (signature was
    already correct, only the title was wrong)

kvdb.md:
  - Add previously missing property_list_binary API
  - Split four composite sections so each public API has its own
    '### name' entry (per api-doc-standards.md):
    * property_get_bool/int32/int64_with_err -> 3 separate entries
    * property_set_bool/int32/int64 -> 3 separate entries
    * property_set_bool/int32/int64_oneway -> 3 separate entries
    * property_set_buffer / property_set_buffer_oneway -> 2 separate entries

Coverage:
  - uorb.md:  48 / 48 public APIs in apps/system/uorb/uORB/uORB.h (100%)
  - kvdb.md:  31 / 31 public APIs in frameworks/system/utils/include/
              kvdb.h + cutils/properties.h (100%)

Both files retain their existing openvela implementation notes and
functional grouping; all new sections follow the same format (Chinese
description, **参数** list, **返回值** section).

Every new signature has been verified against the source headers.
@tanghao-xiaomi tanghao-xiaomi force-pushed the refactor-uorb-kvdb-api branch from 265ec81 to fff4db4 Compare May 8, 2026 09:48
@tanghao-xiaomi tanghao-xiaomi merged commit 4a405a3 into open-vela:dev May 8, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants