Skip to content

Improve wording of info.description in API definitions - #208

Open
jimfengjinhua wants to merge 1 commit into
camaraproject:mainfrom
jimfengjinhua:fix/issue202-info-description-tweaks
Open

jimfengjinhua wants to merge 1 commit into
camaraproject:mainfrom
jimfengjinhua:fix/issue202-info-description-tweaks

Conversation

@jimfengjinhua

@jimfengjinhua jimfengjinhua commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

What type of PR is this?

Add one of the following kinds:

  • documentation

What this PR does / why we need it:

Addresses the review comments on the info.description sections in #202.

Dedicated Network - Accesses API

  • Explains what the device status is: the status of the device's access to the dedicated network in the context of the access (REQUESTED, GRANTED or DENIED), with a link to the state description in the General Description.
  • "query the status of the Access" now reads "query information about the Access", since an Access has no status.
  • The per-device 429 QUOTA_EXCEEDED result is no longer described as "the device status".
  • The callback description now refers to "a device's access status" instead of "the network access request status".

Dedicated Network - Areas API

  • Lines 47 and 63 reworded as suggested.

Dedicated Network - Network Profiles API

  • "in conjunction with", "API" instead of "API family", "generously", "not all devices use connectivity", "pertaining to all".

Dedicated Network - Networks API

  • The callback description now refers to "the network status" instead of "the network request status".

Which issue(s) this PR fixes:

Fixes #202

Special notes for reviewers:

On "status" vs "state": we've kept both terms deliberately, using each as English normally does.

  • status is the attribute: "the status is GRANTED", "status change".
  • state is one of the values it takes: "in GRANTED state", "transitions to DENIED state".

This matches the existing DeviceStatus and NetworkStatus schema descriptions and the INVALID_STATE error code, so the Networks API needed no further changes. Places where "status" or "state" was used wrongly have been fixed.

Changelog input

Improved info.description wording in all Dedicated Networks APIs (#202): Accesses API now explains the per-device access status (REQUESTED/GRANTED/DENIED) and uses status/state consistently; grammar and wording fixes in the Areas, Network Profiles and Networks APIs.

Additional documentation

This section can be blank.

docs

Address documentation review comments:
- Accesses: explain the per-device access status, fix status/state
  usage, clarify the 429 error result and the callback description
- Areas: clarify that areas are available to the API consumer
- Network Profiles: grammar fixes, replace "API family" with "API"
- Networks: clarify the callback description

Fixes camaraproject#202

@tlohmar tlohmar left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Looks good. We need to merge this soon to prevent collisions

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.

Small info.description documentation tweeks

2 participants