alexey.zholtikov/upm
1
0
Fork 0
mirror of https://github.com/eclipse/upm.git synced 2025-03-15 04:57:30 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: updated sections on porting and documentation authoring

Browse Source 
Signed-off-by: Mihai Tudor Panu <mihai.tudor.panu@intel.com>
This commit is contained in:
Mihai Tudor Panu 2017-02-09 16:45:48 -08:00
parent bd8104f6ee
commit a53ab5cb80
2 changed files with 366 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
README.md
View File

@ -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
View 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. |