diff --git a/README.md b/README.md index 37a8f143..a8b0c3f3 100644 --- a/README.md +++ b/README.md @@ -94,24 +94,34 @@ See building documentation [here](docs/building.md). ### 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). +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). - -Don't forget to check the documentation [section](docs/documentation.md). - +Then, please go over this short set of rules for new [contributions](docs/contributions.md). 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 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 ============== diff --git a/docs/guidelines.md b/docs/guidelines.md new file mode 100644 index 00000000..471f881d --- /dev/null +++ b/docs/guidelines.md @@ -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) + +# Code Commenting Guidelines + +## Grammar + +### Active vs passive voice + +Where possible, prefer active voice over passive. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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.
- To put it into the configuration mode, ground the CONFIG pin on the transceiver.
- Put it into the configuration mode by grounding the CONFIG pin on the transceiver. | + +### Capitalization + +- Capitalize the first word in the description of an entity. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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. + +| **Incorrect** | **Correct** | +| --- | --- | +| Returns True on success, false otherwise | - Returns true on success, false otherwise
- Returns True on success, False otherwise | + +### No possessive case + +Do not use possessive case to avoid unnecessary personalization. + +| **Incorrect** | **Correct** | +| --- | --- | +| method's output | - method output
- output of the method | + +### Present tense + +Use the present simple tense instead of future, past, or present perfect. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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… | + +### Second person vs the user / reader / programmer / engineer + +Use second person when addressing the target reader of your comment. + +| **Incorrect** | **Correct** | +| --- | --- | +| The user can easily override this method. | You can easily override this method. | + +### Third person vs infinitive + +Use third-person verb forms in short descriptions of classes, methods, functions, etc., not infinitive. + +| **Incorrect** | **Correct** | +| --- | --- | +| Get the proximity value from the sensor | Gets the proximity value from the sensor | + +## Punctuation + +### Comma in enumerations + +Add an extra comma before the last item in a list joined by **and** / **or**. + +| **Incorrect** | **Correct** | +| --- | --- | +| Returns raw values for the X, Y and Z axes. | Returns raw values for the X, Y, and Z axes. | + +### No period at the end of description + +Do not put a period if the description of an entity is one sentence long. + +| **Incorrect** | **Correct** | +| --- | --- | +| Returns the name of the sensor. | Returns the name of the sensor | +| Sets the frequency modulation
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
-1 means waiting forever (default) | @param millis Maximum time in milliseconds to wait for the input. -1 means waiting forever (default). | + +**Exception:** if the description contains more than one sentence, put periods after each sentence. + +## Specific word usage + +### Abbreviations and acronyms + +- Spell out the first occurrence or the first prominent use of an abbreviation or acronym, followed by a shortened form. + +| **Incorrect** | **Correct** | +| --- | --- | +| @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. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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. + +| **Incorrect** | **Correct** | +| --- | --- | +| - LCD display
- ISR routine | - LCD / liquid-crystal display
- ISR / interrupt service routine | + +### 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. + +| **Incorrect** | **Correct** | +| --- | --- | +| - 4 wire stepper motor
- 3 axis gyroscope
- zero based indexing
- one byte register | - 4-wire stepper motor
- 3-axis gyroscope
- zero-based indexing
- one-byte register | + +### 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. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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. | + +### Function vs method + +If a function is associated with a class, use **method** instead. + +| **Incorrect** | **Correct** | +| --- | --- | +| class WheelEncoder {
...
/**
* Starts the counter. This function also clears
* the current count and resets the clock.
*/
void startCounter(); | class WheelEncoder {
...
/**
* Starts the counter. This method also clears
* the current count and resets the clock.
*/
void startCounter(); | + +### Onboard vs on-board + +Use **onboard**. + +| **Incorrect** | **Correct** | +| --- | --- | +| This ADC features an on-board reference and oscillator. | This ADC features an onboard reference and oscillator. | + +### Sensor name vs sensor model + +Use a sensor name alone or a sensor model followed by a sensor name, not a sensor model alone. + +| **Incorrect** | **Correct** | +| --- | --- | +| ADXL345 is compatible with… | - The ADXL345 3-axis digital accelerometer is compatible with…
- The accelerometer is compatible with… | + +**Exception:** you can use a sensor model alone when introducing a +sensor for the first time: + +ADXL345 is a 3-axis digital accelerometer… + +### Setup vs set up + +**Setup** is a noun, **set up** is a verb. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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... | + +### Wi-Fi vs WiFi / Wifi / Wi-fi / wifi / wi-fi + +Use **Wi-Fi**. + +| **Incorrect** | **Correct** | +| --- | --- | +| It was tested with the XBee\* S6B WiFi module. | It is tested with the XBee\* S6B Wi-Fi\* module. | + +## Trademarks + +### Intel products + +Use the correct official names of Intel products. When in doubt, check the TM names database. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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. + +### 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. + +| **Incorrect** | **Correct** | +| --- | --- | +| The Grove MQ2 Gas Sensor module is useful for gas leakage detection. | The Grove\* MQ2 Gas Sensor module is useful for gas leakage detection. | + +### Trademark + noun + +Always follow trademarks by an appropriate noun. For a list of approved nouns for a particular trademark, check the TM names database. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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. | + +# Documentation Authoring Guidelines + +## Grammar + +### Capitalization + +For titles, use sentence capitalization. + +| **Incorrect** | **Correct** | +| --- | --- | +| Add a New Device | Add a new device | + +## Styling + +### Bolding + +For GUI elements and file names, use bolding instead of quotes. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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. | + +### Backticks + +Enclose program commands, code blocks, and file paths in backticks (\`). + +| **Incorrect** | **Correct** | +| --- | --- | +| 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`). | + +### Links + +Do not use embedded links to third-party websites. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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. | + +### Numbered list vs bullet points + +- For a logical sequence of steps, use a numbered list. + +| **Incorrect** | **Correct** | +| --- | --- | +| 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:
…
Click on the "Apply" button to save these settings.
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:
1. Go to **Run configurations** and, in the **Commands to execute before application** field, type the following:
…
2. Click the **Apply** button to save these settings.
3. Click the **Run** button to run the code on your board. | + +- For a list of equally important options, use a bulleted list. + +| **Incorrect** | **Correct** | +| --- | --- | +| From this exercise, developers will learn how to:
1. Connect the Intel® Edison board...
2. Run these code samples in the Intel® System Studio IoT Edition...
3. Set up a web application server... | From this exercise, developers will learn how to:
- Connect the Intel® Edison board…
- Run these code samples in the Intel® System Studio IoT Edition…
- Set up a web application server… | + +## Specific word usage + +### Login vs log in + +**Login** is a noun, **log in** is a verb. + +| **Incorrect** | **Correct** | +| --- | --- | +| Provide your log in and password. | Provide your login and password. | +| Login to your account. | Log in( )to your account. | + +### Click + +Omit **on** after **click**. + +| **Incorrect** | **Correct** | +| --- | --- | +| Click on **Advanced system settings**. | Click **Advanced system settings**. | + +### SSH + +Do not use SSH as a verb. It is considered slang and is to be avoided. + +| **Incorrect** | **Correct** | +| --- | --- | +| SSH into your Intel® Edison board. | Establish an SSH connection to your Intel® Edison board. |