mirror of
https://github.com/eclipse/upm.git
synced 2025-03-15 04:57:30 +03:00
docs: updated sections on porting and documentation authoring
Signed-off-by: Mihai Tudor Panu <mihai.tudor.panu@intel.com>
This commit is contained in:
parent
bd8104f6ee
commit
a53ab5cb80
26
README.md
26
README.md
@ -94,24 +94,34 @@ See building documentation [here](docs/building.md).
|
|||||||
|
|
||||||
### Making your own UPM module
|
### Making your own UPM module
|
||||||
|
|
||||||
Porting [link](docs/porting.md) has more information on making new UPM modules.
|
A quick way to add a new sensor driver is to port existing code from another
|
||||||
|
platform (e.g. Arduino) and swap the IO calls to the MRAA API. This of course
|
||||||
|
assumes either ownership of the original code or licensing that allows
|
||||||
|
unrestricted redistribution.
|
||||||
|
|
||||||
There is also an example available gfor max31855 [sensor](docs/max31855.md).
|
The [porting](docs/porting.md) section has more information on this process,
|
||||||
|
and there is an example available based on the max31855 [sensor](docs/max31855.md).
|
||||||
|
|
||||||
Guide on creating Java [bindings](docs/creating_java_bindings.md).
|
Read more on creating Java [bindings](docs/creating_java_bindings.md) for your
|
||||||
|
new driver.
|
||||||
|
|
||||||
### Naming conventions and rules for new UPM contributions
|
### Guidelines and rules for new UPM contributions
|
||||||
|
|
||||||
Before you begin development, take a look at our naming [conventions](docs/naming.md).
|
Before you begin development, take a look at our naming [conventions](docs/naming.md).
|
||||||
|
The name you pick for a newly added sensor needs to be unique in the UPM library.
|
||||||
|
|
||||||
Also, please read the guidelines for contributions [to UPM](docs/contributions.md).
|
Then, please go over this short set of rules for new [contributions](docs/contributions.md).
|
||||||
|
|
||||||
Don't forget to check the documentation [section](docs/documentation.md).
|
|
||||||
|
|
||||||
Make sure you add yourself as an author on every new code file submitted.
|
Make sure you add yourself as an author on every new code file submitted.
|
||||||
If you are providing a fix with significant changes, feel free to add yourself
|
If you are providing a fix with significant changes, feel free to add yourself
|
||||||
as a contributor. Signing-off your commits is mandatory.
|
as a contributor. Signing-off your commits is mandatory.
|
||||||
|
|
||||||
|
Documenting your code is also a big part of the task. We have a strict set of
|
||||||
|
tags used to classify our sensors and their capabilities. You can find out more
|
||||||
|
about this in our [section](docs/documentation.md) on documenting a sensor API.
|
||||||
|
Finally, if you really want to ensure consistency with the rest of the library,
|
||||||
|
and the intel-iot-devkit repositories in general, take a look at our extensive
|
||||||
|
[author guide](docs/guidelines.md).
|
||||||
|
|
||||||
API Documentation
|
API Documentation
|
||||||
==============
|
==============
|
||||||
|
|
||||||
|
348
docs/guidelines.md
Normal file
348
docs/guidelines.md
Normal file
@ -0,0 +1,348 @@
|
|||||||
|
# Code Commenting And Documentation Authoring Guidelines
|
||||||
|
|
||||||
|
#### [Part I. Code Commenting](#code-commenting)
|
||||||
|
|
||||||
|
[Grammar](#grammar)
|
||||||
|
|
||||||
|
- [Active vs passive voice](#voice)
|
||||||
|
|
||||||
|
- [Capitalization](#capitalization)
|
||||||
|
|
||||||
|
- [No possessive case](#possessive-case)
|
||||||
|
|
||||||
|
- [Present tense](#present-tense)
|
||||||
|
|
||||||
|
- [Second person vs the user / reader / programmer / engineer](#second-person)
|
||||||
|
|
||||||
|
- [Third person vs infinitive](#third-person)
|
||||||
|
|
||||||
|
[Punctuation](#punctuation)
|
||||||
|
|
||||||
|
- [Comma in enumerations](#comma)
|
||||||
|
|
||||||
|
- [No period at the end of description](#period)
|
||||||
|
|
||||||
|
[Specific word usage](#word-usage)
|
||||||
|
|
||||||
|
- [Abbreviations and acronyms](#abbr-acr)
|
||||||
|
|
||||||
|
- [Adjectives containing numbers](#adj-num)
|
||||||
|
|
||||||
|
- [App vs application](#app)
|
||||||
|
|
||||||
|
- [Function vs method](#func-meth)
|
||||||
|
|
||||||
|
- [Onboard vs on-board](#onboard)
|
||||||
|
|
||||||
|
- [Sensor name vs sensor model](#name-model)
|
||||||
|
|
||||||
|
- [Setup vs set up](#setup)
|
||||||
|
|
||||||
|
- [Wi-Fi vs WiFi / Wifi / Wi-fi / wifi / wi-fi](#setup)
|
||||||
|
|
||||||
|
[Trademarks](#trademarks)
|
||||||
|
|
||||||
|
- [Intel products](#intel-prod)
|
||||||
|
|
||||||
|
- [Third-party technology](#third-party)
|
||||||
|
|
||||||
|
- [Trademark + noun](#tm-noun)
|
||||||
|
|
||||||
|
#### [Part II. Documentation Authoring](#doc-authoring)
|
||||||
|
|
||||||
|
[Grammar](#da-grammar)
|
||||||
|
|
||||||
|
- [Capitalization](#da-capitalization)
|
||||||
|
|
||||||
|
[Styling](#da-styling)
|
||||||
|
|
||||||
|
- [Bolding](#da-bolding)
|
||||||
|
|
||||||
|
- [Backticks](#da-backticks)
|
||||||
|
|
||||||
|
- [Links](#da-links)
|
||||||
|
|
||||||
|
- [Numbered list vs bullet points](#da-lists)
|
||||||
|
|
||||||
|
[Specific word usage](#da-word-usage)
|
||||||
|
|
||||||
|
- [Login vs log in](#da-login)
|
||||||
|
|
||||||
|
- [Click](#da-click)
|
||||||
|
|
||||||
|
- [SSH](#da-ssh)
|
||||||
|
|
||||||
|
# <a name="code-commenting"></a>Code Commenting Guidelines
|
||||||
|
|
||||||
|
## <a name="grammar"></a>Grammar
|
||||||
|
|
||||||
|
### <a name="voice"></a>Active vs passive voice
|
||||||
|
|
||||||
|
Where possible, prefer active voice over passive.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| It can be put into the configuration mode by grounding the CONFIG pin on the transceiver. | - You can put it into the configuration mode by grounding the CONFIG pin on the transceiver.<br>- To put it into the configuration mode, ground the CONFIG pin on the transceiver.<br>- Put it into the configuration mode by grounding the CONFIG pin on the transceiver. |
|
||||||
|
|
||||||
|
### <a name="capitalization"></a>Capitalization
|
||||||
|
|
||||||
|
- Capitalize the first word in the description of an entity.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| checks to see if there is data available for reading | Checks to see if there is data available for reading |
|
||||||
|
| @param len length of the buffer | @param len Length of the buffer |
|
||||||
|
|
||||||
|
- Be consistent with the capitalization of boolean values.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| Returns True on success, false otherwise | - Returns true on success, false otherwise<br>- Returns True on success, False otherwise |
|
||||||
|
|
||||||
|
### <a name="possessive-case"></a>No possessive case
|
||||||
|
|
||||||
|
Do not use possessive case to avoid unnecessary personalization.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| method's output | - method output<br>- output of the method |
|
||||||
|
|
||||||
|
### <a name="present-tense"></a>Present tense
|
||||||
|
|
||||||
|
Use the present simple tense instead of future, past, or present perfect.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| When specified, this value will be used in computing the voltage. | When specified, this value is used in computing the voltage. |
|
||||||
|
| Once the data has been read… | Once the data is read… |
|
||||||
|
|
||||||
|
### <a name="second-person"></a>Second person vs the user / reader / programmer / engineer
|
||||||
|
|
||||||
|
Use second person when addressing the target reader of your comment.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| The user can easily override this method. | You can easily override this method. |
|
||||||
|
|
||||||
|
### <a name="third-person"></a>Third person vs infinitive
|
||||||
|
|
||||||
|
Use third-person verb forms in short descriptions of classes, methods, functions, etc., not infinitive.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| Get the proximity value from the sensor | Gets the proximity value from the sensor |
|
||||||
|
|
||||||
|
## <a name="punctuation"></a>Punctuation
|
||||||
|
|
||||||
|
### <a name="comma"></a>Comma in enumerations
|
||||||
|
|
||||||
|
Add an extra comma before the last item in a list joined by **and** / **or**.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| Returns raw values for the X, Y and Z axes. | Returns raw values for the X, Y, and Z axes. |
|
||||||
|
|
||||||
|
### <a name="period"></a>No period at the end of description
|
||||||
|
|
||||||
|
Do not put a period if the description of an entity is one sentence long.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| Returns the name of the sensor. | Returns the name of the sensor |
|
||||||
|
| Sets the frequency modulation<br>Valid values are between 10 and 160 (in kHz) | Sets the frequency modulation. Valid values are between 10 and 160 (in kHz). |
|
||||||
|
| @param millis Maximum time in milliseconds to wait for the input<br>-1 means waiting forever (default) | @param millis Maximum time in milliseconds to wait for the input. -1 means waiting forever (default). |
|
||||||
|
|
||||||
|
<font color="purple">**Exception:**</font> if the description contains more than one sentence, put periods after each sentence.
|
||||||
|
|
||||||
|
## <a name="word-usage"></a>Specific word usage
|
||||||
|
|
||||||
|
### <a name="abbr-acr"></a>Abbreviations and acronyms
|
||||||
|
|
||||||
|
- Spell out the first occurrence or the first prominent use of an abbreviation or acronym, followed by a shortened form.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| @brief API for the GP2Y0A family of IR Proximity Sensors | @brief API for the GP2Y0A family of infrared (IR) Proximity Sensors |
|
||||||
|
|
||||||
|
- Do not use Latin abbreviations.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| Works best with halved values; e.g., 1.0, 0.5, 0.25, etc. | Works best with halved values; for example, 1.0, 0.5, 0.25, and so on. |
|
||||||
|
|
||||||
|
- Know exactly what the abbreviation or acronym means to avoid unnecessary duplication.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| - LCD display<br>- ISR routine | - LCD / liquid-crystal display<br>- ISR / interrupt service routine |
|
||||||
|
|
||||||
|
### <a name="adj-num"></a>Adjectives containing numbers
|
||||||
|
|
||||||
|
Adjectives of the form **number + noun / participle** should be hyphenated. It does not matter if a number is represented by one or more digits or spelled out.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| - 4 wire stepper motor<br>- 3 axis gyroscope<br>- zero based indexing<br>- one byte register | - 4-wire stepper motor<br>- 3-axis gyroscope<br>- zero-based indexing<br>- one-byte register |
|
||||||
|
|
||||||
|
### <a name="app"></a>App vs application
|
||||||
|
|
||||||
|
Use **app** when referring to a program running on a device, and **application** when referring to a program running on a desktop / laptop computer.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| The wiki page for this device includes a link to an Android\* application that can be used to read the device via NFC. | The wiki page for this device includes a link to an Android\* app that can be used to read the device via NFC. |
|
||||||
|
|
||||||
|
### <a name="func-meth"></a>Function vs method
|
||||||
|
|
||||||
|
If a function is associated with a class, use **method** instead.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| class WheelEncoder {<br>...<br>/**<br>* Starts the counter. This function also clears<br>* the current count and resets the clock.<br>*/<br>void startCounter(); | class WheelEncoder {<br>...<br>/**<br>* Starts the counter. This method also clears<br>* the current count and resets the clock.<br>*/<br>void startCounter(); |
|
||||||
|
|
||||||
|
### <a name="onboard"></a>Onboard vs on-board
|
||||||
|
|
||||||
|
Use **onboard**.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| This ADC features an on-board reference and oscillator. | This ADC features an onboard reference and oscillator. |
|
||||||
|
|
||||||
|
### <a name="name-model"></a>Sensor name vs sensor model
|
||||||
|
|
||||||
|
Use a sensor name alone or a sensor model followed by a sensor name, not a sensor model alone.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| ADXL345 is compatible with… | - The ADXL345 3-axis digital accelerometer is compatible with…<br>- The accelerometer is compatible with… |
|
||||||
|
|
||||||
|
<font color="purple">**Exception:**</font> you can use a sensor model alone when introducing a
|
||||||
|
sensor for the first time:
|
||||||
|
|
||||||
|
ADXL345 is a 3-axis digital accelerometer…
|
||||||
|
|
||||||
|
### <a name="setup"></a>Setup vs set up
|
||||||
|
|
||||||
|
**Setup** is a noun, **set up** is a verb.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| It does not require any additional set up. | It does not require any additional setup. |
|
||||||
|
| For instructions on how to setup…, refer to... | For instructions on how to set up…, refer to... |
|
||||||
|
|
||||||
|
### <a name="wi-fi"></a>Wi-Fi vs WiFi / Wifi / Wi-fi / wifi / wi-fi
|
||||||
|
|
||||||
|
Use **Wi-Fi**.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| It was tested with the XBee\* S6B WiFi module. | It is tested with the XBee\* S6B Wi-Fi\* module. |
|
||||||
|
|
||||||
|
## <a name="trademarks"></a>Trademarks
|
||||||
|
|
||||||
|
### <a name="intel-prod"></a>Intel products
|
||||||
|
|
||||||
|
Use the correct official names of Intel products. When in doubt, check the TM names database.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| It is a 64x48 pixel OLED display that connects directly to an edison via its 80-pin connector. | It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison board via its 80-pin connector. |
|
||||||
|
|
||||||
|
**Note:** if an Intel product has a legally approved short name, you may use it in subsequent instances, after spelling it out the first time.
|
||||||
|
|
||||||
|
### <a name="third-party"></a>Third-party technology
|
||||||
|
|
||||||
|
Add an asterisk (\*) after a name to indicate a third-party trademark or registered intellectual property. If you are not sure whether an asterisk is necessary after a particular name, the rule of thumb is to put one, to be on the safe side.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| The Grove MQ2 Gas Sensor module is useful for gas leakage detection. | The Grove\* MQ2 Gas Sensor module is useful for gas leakage detection. |
|
||||||
|
|
||||||
|
### <a name="tm-noun"></a>Trademark + noun
|
||||||
|
|
||||||
|
Always follow trademarks by an appropriate noun. For a list of approved nouns for a particular trademark, check the TM names database.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison via its 80-pin connector. | It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison board via its 80-pin connector. |
|
||||||
|
|
||||||
|
# <a name="doc-authoring"></a>Documentation Authoring Guidelines
|
||||||
|
|
||||||
|
## <a name="da-grammar"></a>Grammar
|
||||||
|
|
||||||
|
### <a name="da-capitalization"></a>Capitalization
|
||||||
|
|
||||||
|
For titles, use sentence capitalization.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| Add a New Device | Add a new device |
|
||||||
|
|
||||||
|
## <a name="da-styling"></a>Styling
|
||||||
|
|
||||||
|
### <a name="da-bolding"></a>Bolding
|
||||||
|
|
||||||
|
For GUI elements and file names, use bolding instead of quotes.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| In the “Environment Variables” window, click “OK”. | In the **Environment Variables** window, click **OK**. |
|
||||||
|
| Copy the “example.zip” archive into the installation directory. | Copy the **example.zip** archive into the installation directory. |
|
||||||
|
|
||||||
|
### <a name="da-backticks"></a>Backticks
|
||||||
|
|
||||||
|
Enclose program commands, code blocks, and file paths in backticks (\`).
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| To create a new device, use the **create-thing** command. | To create a new device, use the \`create-thing\` (rendered as `create-thing`) command. |
|
||||||
|
| Go to **C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws**. | Go to \`C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws\` (rendered as `C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws`). |
|
||||||
|
|
||||||
|
### <a name="da-links"></a>Links
|
||||||
|
|
||||||
|
Do not use embedded links to third-party websites.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| Create an account on [Microsoft Azure](https://azure.microsoft.com/en-us), if you do not yet have one. | Create an account on [https://azure.microsoft.com/en-us](https://azure.microsoft.com/en-us), if you do not yet have one. |
|
||||||
|
|
||||||
|
### <a name="da-lists"></a>Numbered list vs bullet points
|
||||||
|
|
||||||
|
- For a logical sequence of steps, use a numbered list.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| When running your C++ code on the Edison, you need to set the MQTT parameters in Eclipse. Go to "Run configurations", and change the "Commands to execute before application" to the following:<br>…<br>Click on the "Apply" button to save these settings.<br>Click on the "Run" button to run the code on the Edison. | When running your C++ code on the Intel® Edison board, you need to set the MQTT\* client parameters in Eclipse\*. To do that:<br>1. Go to **Run configurations** and, in the **Commands to execute before application** field, type the following:<br>…<br>2. Click the **Apply** button to save these settings.<br>3. Click the **Run** button to run the code on your board. |
|
||||||
|
|
||||||
|
- For a list of equally important options, use a bulleted list.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| From this exercise, developers will learn how to:<br>1. Connect the Intel® Edison board...<br>2. Run these code samples in the Intel® System Studio IoT Edition...<br>3. Set up a web application server... | From this exercise, developers will learn how to:<br>- Connect the Intel® Edison board…<br>- Run these code samples in the Intel® System Studio IoT Edition…<br>- Set up a web application server… |
|
||||||
|
|
||||||
|
## <a name="da-word-usage"></a>Specific word usage
|
||||||
|
|
||||||
|
### <a name="da-login"></a>Login vs log in
|
||||||
|
|
||||||
|
**Login** is a noun, **log in** is a verb.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| Provide your log in and password. | Provide your login and password. |
|
||||||
|
| Login to your account. | Log in( )to your account. |
|
||||||
|
|
||||||
|
### <a name="da-click"></a>Click
|
||||||
|
|
||||||
|
Omit **on** after **click**.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| Click on **Advanced system settings**. | Click **Advanced system settings**. |
|
||||||
|
|
||||||
|
### <a name="da-ssh"></a>SSH
|
||||||
|
|
||||||
|
Do not use SSH as a verb. It is considered slang and is to be avoided.
|
||||||
|
|
||||||
|
| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
|
||||||
|
| --- | --- |
|
||||||
|
| SSH into your Intel® Edison board. | Establish an SSH connection to your Intel® Edison board. |
|
Loading…
x
Reference in New Issue
Block a user