Header levels

Author: Irit Arkin

docs/creating_apps/EventQueue_impl.md

@@ -1,3 +1,3 @@
-## EventQueue implemntation
+## EventQueue implementation
 
 [A document about the particular features and peculiarities of the implementation of the EventQueue.]

docs/creating_apps/code_style.md

@@ -1,10 +1,10 @@
-# Code contributions: GitHub pull requests and code style guide
+## Code contributions: GitHub pull requests and code style guide
 
 The mbed OS codebase is hosted on GitHub, and you can submit new features or bug fixes. Please follow the [guidelines for GitHub pull requests](#guidelines-for-github-pull-requests) and the [coding style guide](#coding-style) in your submissions.
 
 <span class="tips">**Tip:** Please also read the section [Creating and publishing your own libraries and contributing to mbed OS](contributing.md) for a review of the process and legal requirements.</span>
 
-## Guidelines for GitHub pull requests
+### Guidelines for GitHub pull requests
 
 Pull requests on GitHub have to meet the following requirements in order to keep the code and commit history clean:
 
@@ -22,17 +22,17 @@ Pull requests on GitHub have to meet the following requirements in order to keep
 * Because we use GitHub and explicit CLAs, special commit tags that other projects may use, such as “Reviewed-by”, or “Signed-off-by”, are redundant and should be omitted. GitHub keeps track of who reviewed what and when, and our stack of signed CLAs shows us who has agreed to our development contribution agreement.
 * Prefixing your commit message with a domain is acceptable and recommended where it makes sense to do so. However, prefixing one's domain with the name of the repo is not useful. For example, making a commit entitled "mbed-drivers: Fix doppelwidget frobulation" to the mbed-drivers repo would not be acceptable, as it is already understood that the commit applies to "mbed-drivers". Renaming the commit to "doppelwidget: Fix frobulation" would be better, if we presume that "doppelwidget" is a meaningful domain for changes, as it communicates that the change applies to the doppelwidget area of mbed-drivers.
 
-## Code acceptance
+### Code acceptance
 
 [After the CLA](contributing.md) is in place and the code has gone through automated testing, developers will take a look and comment on the pull request. If all is well and acceptable, your code will be ready for merging into the central development branch.
 
-## Coding style
+### Coding style
 
-Whether you're writing new code or fixing bugs in existing code, please follow the mbed OS coding style. 
+Whether you're writing new code or fixing bugs in existing code, please follow the mbed OS coding style.
 
 mbed OS follows the [K&R style](https://en.wikipedia.org/wiki/Indent_style#K.26R_style), with at least two exceptions (which can be found in the list below the code sample).
 
-### Code sample
+#### Code sample
 
 ```c
 static const PinMap PinMap_ADC[] = {
@@ -51,37 +51,37 @@ uint32_t adc_function(analogin_t *obj, uint32_t options)
             timeout = 10;
             break;
     }
-  
+
     while (!adc_hal_is_conversion_completed(instance, 0)) {
         if (timeout == 0) {
             break;
         } else {
             timeout--;
         }
     }
-  
+
     if (obj->adc == ADC_CHANNEL0) {
         adc_measure_channel(instance);
         adc_stop_channel(instance);
     } else {
         error("channel not available");
     }
-    
+
 #if DEBUG
     for (uint32_t i = 0; i < 10; i++) {
         printf("Loop : %d", i);
     }
 #endif
     return adc_hal_get_conversion_value(instance, 0);
-} 
+}
 ```
-### Rules
+#### Rules
 
 * Indentation - four spaces. Please do not use tabs.
 
 * Braces - K&R style.
 
-* One true brace style (1TBS) - use braces for statements of type `if`, `else`, `while` and `for` (exception [from K&R](http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS)). 
+* One true brace style (1TBS) - use braces for statements of type `if`, `else`, `while` and `for` (exception [from K&R](http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS)).
 
 * One line per statement.
 
@@ -95,7 +95,7 @@ uint32_t adc_function(analogin_t *obj, uint32_t options)
 
 * Comments should use proper spelling and grammar.
 
-* For pointers, `*` is adjacent to a name (analogin_t *obj).
+* For pointers, `*` is adjacent to a name (`analogin_t *obj`).
 
 * Don't leave trailing spaces at the end of lines.
 
@@ -107,21 +107,21 @@ uint32_t adc_function(analogin_t *obj, uint32_t options)
 
 * A file should have an empty line at the end.
 
-### Naming conventions
+#### Naming conventions
 
-#### Classes
+##### Classes
 
 * Begins with a capital letter, and each word in it also begins with a capital letter (AnalogIn, BusInOut).
 
 * Methods contain small letters, with words separated by underscore.
 
 * Private members starts with an underscore: ``__User defined types (typedef)))``.
 
-* Structures - suffix _t - to denote it is a user defined type.
+* Structures - `suffix _t` - to denote it is a user defined type.
 
 * Enumeration - the type name and values name - same naming convention as classes (for example MyNewEnum).
 
-#### Functions
+##### Functions
 
 * Contain lower case letters (as methods within classes).
 
@@ -139,17 +139,17 @@ public:
      * @param pin AnalogIn pin to connect to
      * @param name (optional) A string to identify the object
      */
-    AnalogIn(PinName pin) 
+    AnalogIn(PinName pin)
     {
         analogin_init(&_adc, pin);
     }
-	
+
     /** Read the input voltage, represented as a float in the range [0.0, 1.0].
      *
      * @returns
      * 	A floating-point value representing the current input voltage, measured as a percentage
      */
-    uint32_t read() 
+    uint32_t read()
     {
         return analogin_read(&_adc, operation);
     }
@@ -168,7 +168,7 @@ struct analogin_s {
 typedef struct analogin_s analogin_t;
 ```
 
-### Doxygen documentation
+#### Doxygen documentation
 
 All functions and methods should contain documentation using doxgyen.
 
@@ -180,11 +180,11 @@ You can use [Artistic Style (AStyle)](http://sourceforge.net/projects/astyle/fil
 astyle.exe --style=kr --indent=spaces=4 --indents-switches $(full_path_to_file)
 ```
 
-## Compile flags and ABI requirements
+### Compile flags and ABI requirements
 
 All C and C++ code submitted to mbed OS must compile with GCC ARM Embedded, ARM Compiler 5 and IAR EWARM. Code must compile with specific flags for each compiler. See the list of these flags below. The profiles used by the mbed OS tools are each subsets of these flags. Each profile has one optimization setting.
 
-### GCC ARM Embedded
+#### GCC ARM Embedded
 
 Code must be compatible with the `softfp` float ABI. mbed OS uses the following flags when compiling with GCC ARM Embedded.
 
@@ -198,10 +198,10 @@ flag                        | meaning
 `-fno-rtti`                 | Disable runtime type information (C++ only)
 `-Os`                       | Optimize for size
 `-O0`                       | Do not optimize
-`-std=gnu99`                | C uses the GNU99 standard 
+`-std=gnu99`                | C uses the GNU99 standard
 `-std=gnu++98`              | C++ uses the GNU++98 standard
 
-### ARM Compiler 5
+#### ARM Compiler 5
 
 mbed OS uses the following flags when compiling with ARM Compiler 5.
 
@@ -213,7 +213,7 @@ flag       | meaning
 `-O3`      | Optimize for speed
 `-c99`     | C uses the C99 standard
 
-### IAR EWARM
+#### IAR EWARM
 
 mbed OS uses the following flags when compiling with IAR EWARM.
 

docs/creating_apps/contributing.md

@@ -1,4 +1,4 @@
-# Creating and publishing your own libraries and contributing to mbed OS
+## Creating and publishing your own libraries and contributing to mbed OS
 
 This chapter covers the different aspects of developing your own libraries for use in mbed devices, as well as items to keep in mind during development, such as licensing. It covers:
 
@@ -8,17 +8,17 @@ This chapter covers the different aspects of developing your own libraries for u
 
 ### Licensing binaries and libraries
 
-When you write original code, you own the copyright and can choose to make it available to others under a license of your choice. A license gives rights and puts limitations on the reuse of your code by others. Not having a license means others cannot use your code. We encourage you to choose a license that makes possible (and encourages!) reuse by others. 
+When you write original code, you own the copyright and can choose to make it available to others under a license of your choice. A license gives rights and puts limitations on the reuse of your code by others. Not having a license means others cannot use your code. We encourage you to choose a license that makes possible (and encourages!) reuse by others.
 
 If you create new software, such as drivers, libraries and examples, you can apply whatever license you like as the author and copyright holder of that code. Having said that, we encourage you to use a well-known license such as one of the ones listed [on the SPDX License List](http://spdx.org/licenses/), preferably an [OSI-approved] (https://opensource.org/licenses/alphabetical), permissive open source software license. Specifically, we recommend the following:
 
 * For original source code, use the Apache 2.0 license.  
 
 * For binary releases (for example, private source code you can’t or don’t want to release but want to share as a binary library and headers available for others to use), consider the [Permissive Binary License](https://www.mbed.com/licenses/PBL-1.0). This is designed to be compatible with Apache 2.0 and the mbed OS codebase.
 
-* If your software incorporates or is derived from other third party open source code, please be sure to retain all notices and identify the license for the third party licensed code in the same manner as described below. Remember, you cannot change the license on someone else’s code, because you are not the copyright holder! Instead, choose a license that is compatible with the license used by the third party open source code, or use the same license as that code. For example, if your software is derived from GPL source code, GPL requires you to license the rest of your code in that software under the GPL too. Note that many commercial users won’t be able to use GPL source code in their products, so we don't recommend this license if you're not obligated to use it. 
+* If your software incorporates or is derived from other third party open source code, please be sure to retain all notices and identify the license for the third party licensed code in the same manner as described below. Remember, you cannot change the license on someone else’s code, because you are not the copyright holder! Instead, choose a license that is compatible with the license used by the third party open source code, or use the same license as that code. For example, if your software is derived from GPL source code, GPL requires you to license the rest of your code in that software under the GPL too. Note that many commercial users won’t be able to use GPL source code in their products, so we don't recommend this license if you're not obligated to use it.
 
-You must either write all the code you provide yourself, or have the necessary rights to provide code written by someone else. 
+You must either write all the code you provide yourself, or have the necessary rights to provide code written by someone else.
 
 In all cases, whatever license you use, please use an [SPDX license identifier](http://spdx.org/licenses/) in every source file following the recommendations [here](https://spdx.org/spdx-specification-21-web-version#h.twlc0ztnng3b) to make it easier for users to understand and review licenses.
 
@@ -34,7 +34,7 @@ In order to clearly reflect the Apache 2.0 license, please create two text files
 
 * A *LICENSE* file with the following text:</br>
 
-<pre>Unless specifically indicated otherwise in a file, files are licensed under the Apache 2.0 license, 
+<pre>Unless specifically indicated otherwise in a file, files are licensed under the Apache 2.0 license,
 as can be found in: LICENSE-apache-2.0.txt</pre>
 
 * The full original [Apache 2.0 license text](http://www.apache.org/licenses/LICENSE-2.0) in *LICENSE-apache-2.0.txt*
@@ -45,13 +45,13 @@ Each source header should *start with* your copyright line, the SPDX identifier
 Copyright (c) [First year]-[Last year], **Your Name or Company Here**
 SPDX-License-Identifier: Apache-2.0
 
-Licensed under the Apache License, Version 2.0 (the "License"); 
+Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 
 You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
-Unless required by applicable law or agreed to in writing, software 
-distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, 
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
 either express or implied.
 
 See the License for the specific language governing permissions and limitations under the License.
@@ -61,7 +61,7 @@ See the License for the specific language governing permissions and limitations
 
 The Permissive Binary License (PBL) is a permissive license based on BSD-3-Clause and designed specifically for binary blobs. It's minimal but covers the basics, including an express patent grant.
 
-It allows you to share a binary blob and the relevant headers, and allows others to use that binary blob as part of their product - as long as they provide it with all the relevant dependencies and don't modify it or reverse engineer it. 
+It allows you to share a binary blob and the relevant headers, and allows others to use that binary blob as part of their product - as long as they provide it with all the relevant dependencies and don't modify it or reverse engineer it.
 
 The full text can be found on [mbed.com](https://www.mbed.com/licenses/PBL-1.0).
 
@@ -71,7 +71,7 @@ In order to clearly reflect the PBL license, please create three text files:
 
 * A *LICENSE* file with:
 
-<pre>Unless specifically indicated otherwise in a file, files are licensed under the Permissive Binary License, 
+<pre>Unless specifically indicated otherwise in a file, files are licensed under the Permissive Binary License,
 as can be found in: LICENSE-permissive-binary-license-1.0.txt</pre>
 
 * The full original [Permissive Binary License 1.0 text](https://www.mbed.com/licenses/PBL-1.0) in *LICENSE-permissive-binary-license-1.0.txt*.
@@ -104,56 +104,56 @@ If you decide to use a different license for your work, follow the same pattern:
 
 * If more than one license applies to the source file, then use an SPDX license expression (see [SPDX Specification, Appendix IV](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60)), to reflect the presence of multiple licenses in your *LICENSE* file and in each source file.
 
-## Contributing to the mbed OS codebase
+### Contributing to the mbed OS codebase
 
-### mbed OS principles
+#### mbed OS principles
 
 mbed OS uses these same basic principles for its source code and library distributions. So source code we own is distributed under the Apache 2.0 license, and binary blobs are released under the Permissive Binary License. Software parts from third parties that were already licensed under a different license are available under that original license.
 
 All the source code and binary blobs that end up in mbed OS are maintained in public GitHub repositories.
 
-### Contributions
+#### Contributions
 
 All code changes and additions to mbed OS are handled through GitHub. If you want to contribute, either by adding features or by fixing bugs, please follow the guidelines for [new features](#contributing-new-features-to-mbed-os) and [bugs](#reporting-and-fixing-bugs), and in both cases please follow the [code style guide and GitHub pull request guidelines](code_style.md).
 
-### Inbound License for Contributions
+#### Inbound License for Contributions
 
-If you want to contribute code to mbed OS, you must sign an mbed Contributor License Agreement (CLA). Please ask for a CLA before submitting any code (for example, while discussing the issue on GitHub), then wait for ARM to confirm acceptance of your CLA before making contributions. 
+If you want to contribute code to mbed OS, you must sign an mbed Contributor License Agreement (CLA). Please ask for a CLA before submitting any code (for example, while discussing the issue on GitHub), then wait for ARM to confirm acceptance of your CLA before making contributions.
 
 <span style="background-color:#E6E6E6;border:1px solid #000;display:block; height:100%; padding:10px">**Note:** If you publish a feature or a solution to a problem before signing the CLA, then find out that you are not able or allowed to sign the CLA, we will not be able to use your solution anymore. That may prevent us from solving the problem for you.</span>
 
-When you ask for the CLA, we'll send you the agreement and ask you to sign it *before* we handle any pull request from you: 
+When you ask for the CLA, we'll send you the agreement and ask you to sign it *before* we handle any pull request from you:
 
 * Individuals who want to contribute their own work must sign and return an Individual CLA.
 
 * Companies that want employees to contribute on its behalf must sign and return a Corporate CLA.
 
 The same agreement is then valid for all future pull requests from that GitHub username.  
 
-### Contributing new features to mbed OS
+#### Contributing new features to mbed OS
 
 Before contributing an enhancement (new feature, new port and so on) please [discuss it on the forums](https://developer.mbed.org/forum/) to avoid duplication of work, as we or others might be working on a related feature.
 
 Patch contributions can only be accepted through GitHub by creating a pull request from forked versions of our repositories. This allows us to review the contributions in a user friendly and reliable way, under public scrutiny.
 
 Please create separate patches for each concern; each patch should have a clear unity of purpose. In particular, separate code formatting and style changes from functional changes. This makes each patch’s true contribution clearer and therefore quicker and easier to review.
 
-### Reporting and fixing bugs
+#### Reporting and fixing bugs
 
 Before submitting a bug report or a bug fix, please [discuss it on the forums](https://developer.mbed.org/forum/) to avoid duplication of work, as we or others might be working on it already.
 
-#### Bug reports (issues) on GitHub
+##### Bug reports (issues) on GitHub
 
 All mbed OS is on GitHub; please use GitHub's [issues mechanism](https://guides.github.com/features/issues/) to open a bug report directly against the relevant GitHub repository.
 
-#### Bug fixes
+##### Bug fixes
 
-Please refer to the [code contributions chapter](code_style.md). 
+Please refer to the [code contributions chapter](code_style.md).
 
-Bug fixes must be verified by a member of the mbed team before they're pulled into the main branch. You must therefore use GitHub to fork the repo, then submit a pull request with your changes. 
+Bug fixes must be verified by a member of the mbed team before they're pulled into the main branch. You must therefore use GitHub to fork the repo, then submit a pull request with your changes.
 
 The last line in your commit message description should say “Fixes #deadbeef”, where “deadbeef” is the issue number in GitHub. This allows GitHub to automatically close the issue when the commit is merged into the default branch.
 
-## Further reading
+### Further reading
 
 Please see the [code contributions chapter](code_style.md) for the guidelines to GitHub pull requests and the coding style guide.