documentation update

CONTRIBUTING.md

@@ -3,56 +3,105 @@
 
 ----
 
-## Contributing Guide
+# Awa LightweightM2M contributor guide.
 
-### Reporting a bug.
 
-So you have found a bug, or just generally an area which can be improved and wish to report it.
+## Reporting issues and bugs.
 
-Navigate to the "Issues" tab on the project github page https://github.com/FlowM2M/AwaLWM2M/issues and click the "New Issue" button.
+If you discover a bug, or find an issue or area that you feel needs improvement:
 
-When reporting your bug, please try and be as descriptive as possible. consider adding the following information.
+* Navigate to the "Issues" tab on the project github page https://github.com/FlowM2M/AwaLWM2M/issues  
 
-```
-Description of the problem:
+* Click the "New Issue" button.  
 
-Awa LWM2M Version or commit id:
 
-Environment details (OS/Distribution etc):
+When making your report, be as clear and concise as possible. Use the following list as a guide:
 
-Reproduciblity/Frequency:
 
-Steps to Reproduce/What you were doing when the bug occured:
 
-Excepted Result:
+* Describe the issue, and why you believe it's a problem. 
 
-Actual Result:
+* Include the Awa LWM2M version or commit id.
+
+* Describe environment details (OS/distribution etc).
+
+* State how often the issue has occurred.
+
+* Describe the steps to take to uncover or reproduce the issue (if any).
+
+* Expected behaviour.
+
+* Actual behaviour.
+
+* Any additional infomation, log output etc.
+
+
+----
+
+
+## Developer submissions.
 
-Addition Infomation (log output etc)
-```
 
 ### Branching model.
 
 All Awa LWM2M development occurs on the master branch. Developers should only submit patches against the master branch.
 
+
 ### Setting up your development machine.
 
 Configure your user name to be used by git:
 
     $ git config --global user.name "FirstName LastName"
     $ git config --global user.email "[email protected]"
 
+
 ### Coding style.
 
-The Awa LWM2M coding style guidelines can be found in the [Coding style guide](doc/coding_style.md)
+The Awa LWM2M coding style guidelines can be found in the [coding style guide](doc/coding_style.md).
+
+
+
+### Commit messages.
+
+For the commit message, the following rules apply:
+
+ * The first line should be a brief summary of the patch.
+ * Leave a blank line after the summary.
+ * Provide a detailed description of the change.
+ * Leave a blank line after the description.
+ * If the patch relates to an issue, add a line with 'Ref: ISSUE_ID'.
+ * Add a Gerrit 'Change-id' line.
+ * Add a Git 'Signed-off-by' line using ````git commit -s```` or ````git commit --sign-off```` (see *Signing your work* below).
+
+ Example:
+
+````
+
+    Adds a new example feature xyz
+
+    This patch adds example feature xyz. This feature merely acts
+    as an example of how to commit something to the project.
+    For real features this would contain some text
+    describing in detail what the new feature actually does.
+
+    Ref: AWA-2131
+    Change-Id: Id564ab1230913abf88123dff193b1231b1
+    Signed-off-by: User Name <[email protected]>
+
+````
+
+
 
 ### Signing your work.
 
-Awa LWM2M requires contributors to accept the Developer Certificate of Origin (DCO) (from developercertificate.org)
+Awa LWM2M requires contributors to accept the Developer Certificate of Origin (DCO) from developercertificate.org.
+
+The sign-off is a single line at the end of your commit comment to certify that you either wrote the supplied code or otherwise have the right to pass on the code as open source.
+
+
+Certifying your contribution asserts that *for the current submission* the following statement is true:
 
-The sign-off is a single line at the end of your commit comment which certifies that you wrote the supplied code or otherwise have the right to pass it on the code as open-source.
 
-It's pretty simple: if you can certify the following:
 
 ```
 Developer Certificate of Origin
@@ -92,43 +141,23 @@ By making a contribution to this project, I certify that:
     this project or the open source license(s) involved.
 ```
 
-Then you just add the following line to every git commit message to indicate that you accept the DCO:
-
-```
-Signed-off-by: User Name <[email protected]>
-```
-
-If you set-up your user.name and user.email via git config, you can sign your commit automatically with git commit like so:
-
-```
-git commit --signoff
-```
 
-### Commit messages.
+To certify your submission just add the following line to *every* git commit message to indicate that you accept the above DCO:
 
-For the commit message, the following rules apply:
 
- * The first line should be a brief summary of the patch.
- * Leave a blank line after the summary.
- * Provide a detailed description of the change.
- * Leave a blank line after the description.
- * If the patch relates to an issue, add a line with 'Ref: ISSUE_ID'.
- * Add a Gerrit 'Change-id' line.
- * Add a Git 'Signed-off-by' line (using `git commit -s` or `git commit --sign-off`).
+````
+Signed-off-by: User Name <[email protected]>
 
- Example:
+````
 
-    Adds a new example feature xyz
+If you set-up your user.name and user.email via git config, you can sign your commit automatically with git commit:
 
-    This patch adds example feature xyz. This feature merely acts
-    as an example of how to commit something to the project.
-    For real features this would contain some text
-    describing in detail what the new feature actually does.
-
-    Ref: AWA-2131
-    Change-Id: Id564ab1230913abf88123dff193b1231b1
-    Signed-off-by: User Name <[email protected]>
+````
+git commit --signoff
+````
 
+----
 
+----
 
 

README.md

@@ -13,8 +13,13 @@ The LWM2M protocol has been designed to be highly efficient in terms of data tra
 
 Awa LWM2M is an implementation of the OMA Lightweight M2M protocol that provides a secure and standards compliant device management solution to simplify the development of M2M applications by providing an intuitive API that enables customization without the need for an intimate knowledge of M2M protocols.
 
+
+![Awa application overview](doc/Awa_application_overview.png)
+
+
 Awa LWM2M is a development suite that provides a number of components and tools which can be combined in various ways depending on requirement. For example:
 
+
 * When running on a larger Linux based device, Awa LWM2M can be deployed as a series of daemons that interact with your application via the libawa library and associated API.
 * For more constrained devices, your application code can be built against the constrained device centric API and compiled along with the Awa LWM2M client code into a binary to be deployed on your device.
 
@@ -28,59 +33,55 @@ The easiest way to get started with Awa LWM2M is on a Linux PC.  The following i
 
 Firstly, to obtain a copy of the Awa LWM2M source code:
 
- 1. Sign up for a Github account
+ * Sign up for a Github account  
 
- 2. Install Git
+ * Install Git:  ```` sudo apt-get install git ````  
 
-```
-     sudo apt-get install git 
-```
+ * Clone the repository: ```` git clone https://github.com/FlowM2M/AwaLWM2M.git ````   
 
- 3. Clone the repository 
-```
-     git clone https://github.com/FlowM2M/AwaLWM2M.git
-``` 
 
-Further instructions can be found in the [Getting started guide](doc/starters_guide.md).
+Further information can be found in the [Quick start guide](doc/starters_guide.md).
 
 ----
 
 ### Documentation.
 
-Awa LWM2M documentation is available both at a general level (project information, user and developer guides), and a techinical level (the API guide). All documentation is available in this repository. The *doc* directory contains information relating the project in general, and the *api/doc* directory contains the lower level documentation for the Awa API.
+Awa LWM2M documentation is available both at a general level (project information, user and developer guides), and a techinical level (the API guide). All documentation is available in this repository. The *doc* directory contains information relating to the project in general, and the *api/doc* directory contains the lower level documentation for the Awa API.
 
-#### General documentation.
+Note that for our purposes the terms *user* and *developer* have the following definitions:
+
+* *User* - An M2M application developer who uses the tools and libraries supplied by this project as the foundation of, or enhancement to, their own M2M application.  
+* *Developer* - A developer who develops for and contributes to the Awa LightweightM2M project. 
 
-* For build instructions see the [Getting started guide](doc/starters_guide.md)
-* Examples of how to use the tools can be found in the  [User guide](doc/userguide.md) 
-* For developers, an overview of the system can be found in the [Developer guide](doc/developer_guide.md)
-* Information regarding the testing framework, can be found in the [Testing](doc/testing.md) guide.
+
+#### General documentation.
+
+* For project users:  
+	* For build instructions, see the [Quick start guide](doc/starters_guide.md). 
+	* Examples of how to use the tools can be found in the [User guide](doc/userguide.md).
+* For contributing developers:
+	* An overview of the system can be found in the [Developer guide](doc/developer_guide.md).  
+	* Information regarding the testing framework, can be found in the [Testing](doc/testing.md) guide.  
 
 #### API guide.
 
 The Awa API documentation is available as a Doxygen presentation which is generated via the following process.
 
-  1. Install [Doxygen ](http://www.stack.nl/~dimitri/doxygen/download.html)
+  1. Install [Doxygen ](http://www.stack.nl/~dimitri/doxygen/download.html): ```` sudo apt-get install doxygen````
 
-```
-    sudo apt-get install doxygen
-```
+  2. Generate the documentation: ```` make docs````
 
-  2. Generate the documentation
-```
-    make docs
-```
-  The output can be found in the api/doc/html directory and viewed by opening index.html with your web browser.
+The output can be found in the api/doc/html directory and viewed by opening index.html with your web browser.
 
-For convenience you can also find the latest version of this documentation [here]()
+For convenience you can also find the latest version of this documentation [here]().
 
 ----
 
 ### Contributing.
 
-We welcome all contributions to this project and we give credit where it's due. Anything from enhancing functionality, to improving documentation and bug reporting - it's all good. 
+We welcome all contributions to this project and we give credit where it's due. Anything from enhancing functionality to improving documentation and bug reporting - it's all good. 
 
-Find out more in the [Contributing guide](CONTRIBUTING.md).
+Find out more in the [contributor guide](CONTRIBUTING.md).
 
 ### Credits.
 
@@ -96,9 +97,9 @@ We would also like to acknowledge and thank the authors of the following project
 
 ### License information.
 
-* All code and documentation developed by Imagination Technologies Limited is licensed under the [BSD 3-clause license](LICENSE)
-* LibCoAP by Olaf Bergmann is licensed under the GNU General Public License (GPL), Version 2 or higher, OR the simplified BSD license
-* Jsmn by Serge A. Zaitsev is licensed under the MIT license
+* All code and documentation developed by Imagination Technologies Limited is licensed under the [BSD 3-clause license](LICENSE).  
+* LibCoAP by Olaf Bergmann is licensed under the GNU General Public License (GPL), Version 2 or higher, OR the simplified BSD license.  
+* Jsmn by Serge A. Zaitsev is licensed under the MIT license.  
 
 ----
 

doc/coding_style.md

@@ -1,5 +1,5 @@
 
-![](doc/img.png)
+![](img.png)
 
 ----
 
@@ -9,6 +9,11 @@
 
 ## Coding style guide.
 
+It's important to that coding style remains consistent throughout the project to ensure that all contributors and project administrators are able to easily decipher code blocks, comments, syntax etc. 
+Always consider that another contributor may one day continue to build on your submissions. Make it easy for them by adopting the style outlined below.
+
+### General layout.
+
 The sample code below illustrates the preferred use of indentation, bracing and white space:
 
 ````
@@ -60,7 +65,7 @@ typedef struct
 **Notes.** 
 
 * A structure type definition doesn't usually need both a structure name and typedef name (a struct name is not given in the above example). One possible exception to this rule is where the typedef name is declaring a structure-pointer type.  
-* The use of suffix *_e* in enums is not preferred. 
+* The use of suffix *_e* in enums is discouraged. 
 * To avoid namespace problems in 'C' each value should be prefixed by the enum name. For example:
 ````
 typedef enum
@@ -88,11 +93,11 @@ Bitfields also have a code size and performance overhead due to the need to be p
 
 Structure field names should use Pascal casing (e.g. ThisPerson.Age).
 
-### Header Files.
+### Header files.
 
 All public functions, variables and definitions must be declared in a header file. Most .c modules should have a corresponding .h file to be included (both within the module and elsewhere). It is poor form to make the compiler try to guess how to resolve undeclared function calls in other modules.
 
-## Commenting.
+### Code commenting.
 Single line comments should use *//*. For example:
 ````
 void MyFunction(void)
@@ -107,7 +112,7 @@ void MyFunction(void)
 }
 ````
 
-Similarly multi-line comments within a function should be formatted like this:
+Similarly, multi-line comments within a function should be formatted like this:
 ````
 void AwaTask(void *parameters)
 {
@@ -137,7 +142,7 @@ AwaString GetNextEntryFromProcessingQueue()
 }
  ````
 
-### Good/Bad Coding Practise.
+### Good coding practise.
 * Ideally functions should have a single exit point. The use of multiple return points is dangerous and makes it harder to read the code. Always consider what will happen if someone needs to append code to your function.
 
 * Where possible definitions should be used rather than raw values, e.g. use *AllocMessageBuf(MAX_MESSAGE_SIZE)* rather than  *AllocMessagBuf(1024)*. This ensures that all code sharing the same defined value will still work if the 'magic' value is updated.