Improve ble docs #5392
Merged
Improve ble docs #5392
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Improve detailed description of the class. - Add undefined params tparams and return documentation. - Add pre and postcondition when valuable. - Put the elements of the file in the ble.common group.
- The class has been documented with a detailed example and explanation of its responsabilities. - Members have been reordered and regrouped logically. - Deprecated annotation has been added to relevant members. - BLE::BLE, BLE::waitForEvent has been deprecated to match with their existing description.
|
@AnotherButler @marcbonnici Could you review the additions I made to the documentation ? |
marcbonnici
reviewed
Oct 30, 2017
features/FEATURE_BLE/ble/BLE.h
Outdated
| OnEventsToProcessCallback_t; | ||
|
|
||
| /** | ||
| * Register a callback called when the BLE stack has pending work. |
| * | ||
| * @return BLE_ERROR_NONE if the underlying stack and all other services of | ||
| * the BLE API were shutdown correctly. | ||
| * Call to this function is initiated by BLE::init, instanceID identify the |
There was a problem hiding this comment.
I think this could do with rewording slightly.
"Call to this function is initiated by.." -> "Calls to this function are initiated by.." or "A call to this function is initiated by.."
| * Accessor to GattServer. This function is used by BLE::gattServer(). | ||
| * Accessor to the vendor implementation of the Gap interface. | ||
| * | ||
| * @return A reference to a Gap object associated to this BLE instance. |
There was a problem hiding this comment.
This uses "this BLE instance" and all the following Doc Strings use "this BLEInstanceBase instance". Which one is correct?
| * Return the instance of the vendor implementation of BLEInstanceBase. | ||
| * | ||
| * @important Contrary to its name, this function does not return a new instance | ||
| * at eachcall. It rather act like an accessor to a singleton. |
features/FEATURE_BLE/ble/BLETypes.h
Outdated
| * A connection handle is an unsigned integer capable of holding a pointer. | ||
| * The real type (either a pointer to an object or an integer) is opaque and | ||
| * platform dependent. | ||
| * Opaque reference to a connection |
features/FEATURE_BLE/ble/UUID.h
Outdated
| * - 128 bits UUIDs: Complete representation of an UUID. They are comonly used | ||
| * for user defined UUID. | ||
| * | ||
| * This class act as an addapter over these two kind of UUIDs to allow |
features/FEATURE_BLE/ble/UUID.h
Outdated
| */ | ||
| static const unsigned MAX_UUID_STRING_LENGTH = LENGTH_OF_LONG_UUID * 2 + 4; | ||
|
|
||
| public: | ||
|
|
||
| /** | ||
| * Creates a new 128-bit UUID. | ||
| * construct a 128-bit UUID from a string. |
features/FEATURE_BLE/ble/UUID.h
Outdated
| * upto four of them. The UUID is stored internally as a 16 byte | ||
| * array, LSB (little endian), which is opposite from the string. | ||
| * @note Upper and lower case are supported. | ||
| * @note Hyphens are optional and the string must at most includes up to four |
There was a problem hiding this comment.
"the string must at most includes up to four of them" -> "the string must include at most four." ?
features/FEATURE_BLE/ble/UUID.h
Outdated
| * different service or characteristics on the BLE device. | ||
| * | ||
| * @note We do not yet support 32-bit shortened UUIDs. | ||
| * @note User defined UUID are comonly named vendor-specific UUIDs accross |
features/FEATURE_BLE/ble/UUID.h
Outdated
| * | ||
| * @return true if this != @p other, false otherwise. | ||
| * @return true if both UUIDs are equal and false otherwise. |
There was a problem hiding this comment.
Should be "if both UUIDs are not equal"
Fix typos, spelling and conjugation.
pan-
force-pushed
the
improve-ble-docs
branch
from
119775e to
3c3592a
Compare
|
@marcbonnici Many thanks for the review, it helps a lot. |
added 14 commits
November 7, 2017 16:20
Change passive to active voice.
Make minor copy edits, mostly for nonrestrictive clauses.
Make minor copy edits, mostly for active voice and comma use.
Copy edit, mostly for consistent punctuation.
Copy edit, mostly for consistent tense and consistent use of hyphens.
Make minor copy edits, mostly for consistent tense.
Make minor copy edits for active voice and phrasing.
Copy edit, mostly for consistent tense across documents.
Copy edit for active voice.
Copy edit, mostly for consistent tense and hyphenation.
Copy edit file.
Make copy edits to file.
Copy edit file.
Copy edit file.
AnotherButler
approved these changes
Nov 8, 2017
|
/morph build |
Build : SUCCESSBuild number : 511 Triggering tests/morph test |
Exporter Build : SUCCESSBuild number : 126 |
Test : SUCCESSBuild number : 320 |
0xc0170
added
ready for merge
release-version: 5.6.5
and removed
needs: CI
ready for merge
labels
|
This is dependent on #5060 scheduled for 5.7 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Improve the content of the documentation of most BLE related items.
Elements related to the GattServer and the services have not been updated.
The declarations have been reformatted to be more in line with mbed OS guidelines.
Some elements marked has deprecated in their documentation have been annotated with the
MBED_DEPRECATEDto have the documentation and the code in line.Status
READY
Migrations
NO