doc: Edited the Doxygen documentation

Edit for grammar, consistency, accuracy

Change-Id: I72eb48b546ab15097289469c25dc0c298bae46cb
Signed-off-by: steveballard123 <stephen.r.ballard@intel.com>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>

doc/collaboration/code/doxygen/defines.rst

@@ -3,17 +3,16 @@
 Define Documentation
 ####################
 
-Defines are documented similarly as functions. Some noteworthy
+Defines and functions are documented similarly. Some noteworthy
 differences are:
 
 * The best practice for defines requires the use of the **@def**
   special command.
 
-* Just as with functions we provide a full and a simplified template.
-  The simplified template is also accepted. The syntax used in the
-  simplified template should only be used if you are familiar with
-  Doxygen. Use the full template if you are having problems getting
-  the documentation to generate properly.
+* Just as with functions, we provide a full and a simplified template.
+  The syntax used in the simplified template should only be used if you are familiar with
+  Doxygen. Use the full template if you are having problems
+  generating the documentation properly.
 
 Define Comment Templates
 ************************
@@ -26,7 +25,7 @@ Full template:
      *
      * @brief Brief description of the define.
      *
-     * @details Multiple lines describing in detail what is the
+     * @details Multiple lines describing in detail the
      * purpose of the define and what it does.
    */
 
@@ -39,7 +38,7 @@ Simplified template:
    /**
      * Brief description of the define.
      *
-     * Multiple lines describing in detail what is the
+     * Multiple lines describing in detail the
      * purpose of the define and what it does.
    */
    #define name_of_define
@@ -58,9 +57,8 @@ Correct:
    :emphasize-lines: 2, 3, 5
    :linenos:
 
-Observe how each piece of information is clearly marked. There is no
-confusion regarding to what part of the code the comment belongs thanks
-to the @def on line 2.
+Observe how each piece of information is clearly marked.
+The @def on line 2 ensures that the comment is appropriately linked to the code.
 
 Incorrect:
 

doc/collaboration/code/doxygen/doxygen.rst

@@ -3,13 +3,11 @@
 In-Code Documentation
 #####################
 
-The in-code documentation is automatically extracted from the code. Doxygen
-generates a huge XML tree in :file:`../../../xml` that the :program:`Breathe`
-extension imports into Sphinx.
+Doxygen extracts the in-code documentation automatically from the code. Doxygen
+generates XML files that the :program:`Breathe` extension imports into Sphinx.
 
-The Doxygen pass is independent of the Sphinx pass. Using Breathe to link them together, we can
-reference the code in the documentation and vice-versa. For example, :cpp:type:`K_COMM` and
-:cpp:class:`k_timer` have been modified to have additional information.
+The Doxygen pass is independent from the Sphinx pass. Using Breathe to link them together, we can
+reference the code in the documentation and vice-versa.
 
 .. _doxygen_guides:
 
@@ -17,7 +15,7 @@ In-Code Documentation Guides
 ****************************
 
 Follow these guides to document your code using comments. The |project|
-follows the Javadoc Doxygen comments style. We provide examples on how to
+follows the Javadoc / Doxygen commenting style. We provide examples on how to
 comment different parts of the code. Files, functions, defines, structures,
 variables and type definitions must be documented.
 
@@ -30,32 +28,31 @@ the documentation:
 
 #. Start and end a comment block with :literal:`/**` and :literal:`*/`
 
-#. Start each line of the comment with :literal:` * `
+#. Start each line of the comment with :literal:`*`
 
 #. Use \@ for all Doxygen special commands.
 
 #. Files, functions, defines, structures, variables and type
    definitions must have a brief description.
 
-#. All comments must start with a capital letter and end in a period.
-   Even if the comment is a sentence fragment.
+#. All comments must be in sentence-form: begin with a capital letter and
+   end in a period, even when the comment is a sentence fragment.
 
 .. note::
-
-   Always use :literal:`/**` This is a comment. :literal:`*/` if that
-   comment should become part of the documentation.
-   Use :literal:`/*` This comment won't appear in the documentation :
-   literal:`*/` for comments that you want in the code but not in the
-   documentation.
+   Always use this syntax when your intention is to have that comment
+   become part of the documentation.
+   :literal:`/** This comment style will show up in docs. */`
+   Alternatively, use the single-asterisk syntax when your intention
+   is for that comment to appear in the code, but not in the documentation.
+   :literal:`/* This style of comment won't appear in the docs */`
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-
-   files.rst
-   functions.rst
-   variables.rst
-   defines.rst
-   structs.rst
-   typedefs.rst
-   groups.rst
+   files
+   functions
+   variables
+   defines
+   structs
+   typedefs
+   groups

doc/collaboration/code/doxygen/files.rst

@@ -9,8 +9,8 @@ beginning of the file. The file header must contain:
 #. The filename. Use **@file** for Doxygen to auto-complete the
    filename.
 
-#. The brief description: A single line summarizing the contents of
-   the file. Use **@brief** to clearly mark the brief description.
+#. The brief description: A single line summarizing the file contents.
+   Use **@brief** to clearly mark the brief description.
 
 #. The detailed description: One or multiple lines describing the
    purpose of the file, how it works and any other pertinent
@@ -20,7 +20,7 @@ beginning of the file. The file header must contain:
 
    Doxygen has special commands for copyrights (@copyright), authors
    (@author), and other important information. Refer to the
-   `Doxygen documentation`_ for further details.
+   `Doxygen documentation`_ for details.
 
 .. _Doxygen documentation:
    http://www.stack.nl/~dimitri/doxygen/manual/index.html

doc/collaboration/code/doxygen/functions.rst

@@ -4,10 +4,9 @@ Function Documentation
 ######################
 
 Doxygen recognizes a wide variety of syntaxes and structures for the
-function comments. The syntax described here is not the only
-possible one, nor does it exhaust all possible options. If your
-development needs the use of an option not described here, use it.
-However, use the following syntax for everything else:
+function comments. The syntax described here is one of many that are possible.
+If your development requires an option that is not described here, use it.
+However, you may use the following syntax for everything else.
 
 Function Comment Templates
 **************************
@@ -61,8 +60,8 @@ Simplified template:
    my_function(int a, int b){}
 
 .. important::
-   Ensure that there is **no** blank line between the comment block
-   and the function's signature. That way Doxygen can link the comment
+   Ensure that you have **no** blank lines between the comment block
+   and the function's signature. This ensures that Doxygen can link the comment
    to the function.
 
 Function Documentation Examples
@@ -106,8 +105,8 @@ Take the more complex function hello_loop():
    :linenos:
 
 The function parameters have been documented using the correct Doxygen
-command but notice line 1. The comment block was not started with
-:literal:`/**` and therefore Doxygen won't parse it correctly.
+command, yet notice line 1. The comment block was not started with
+:literal:`/**` and, therefore, Doxygen will not parse it correctly.
 
 The parameters have been documented using the \\param command. This is
 equivalent to using @param but incorrect according to these guidelines.
@@ -118,9 +117,9 @@ Notice that there is no blank line between the comment and the
 function's signature, lines 7 and 8. This allows Doxygen to correctly
 link the comment to the function.
 
-Lines 13 and 16 contain two comments that won't be included by Doxygen
-in the documentation. Use the brief description or the detailed
-description inside the comment block to include that information.
+Lines 13 and 16 contain two comments that will not be included by Doxygen
+in the documentation. To include that information, use the brief description or the detailed
+description inside the comment block.
 Remember that variables must be documented separately. See
 :ref:`variable_documentation` for more details.
 
@@ -138,11 +137,9 @@ Comment blocks must have the following structure:
 
 #. Parameter information. See lines 9-11.
 
-#. Return information. Return information is optional for void
-   functions.
+#. Return information. Return information is optional for void functions.
 
-#. Other special commands. There is no specific order for any further
-   special commands.
+#. Other special commands. There is no specific order for any further special commands.
 
 The description of the actions referenced in lines 19 and 21 is part of
 the detailed description in the comment block. The references shown in

doc/collaboration/code/doxygen/structs.rst

@@ -11,8 +11,8 @@ simplified syntax is therefore appropriate.
 
 .. note::
 
-   Follow the same rules as struct when documenting an enum. Use the
-   simplified syntax to add the brief description.
+   Follow the same rules as struct when documenting an enum.
+   Use the simplified syntax to add the brief description.
 
 Structure Comments Template
 ***************************
@@ -24,8 +24,8 @@ Structs only have a simplified template:
    :emphasize-lines: 8
    :linenos:
 
-Doxygen does not require any commands to recognize the different
-comments. It does require that line 8 be left blank though.
+Doxygen does not require any commands to recognize the different comments.
+It does, however, require that line 8 be left blank.
 
 Structure Documentation Example
 *******************************

doc/collaboration/code/doxygen/typedefs.rst

@@ -4,12 +4,12 @@ Type Definition Documentation
 #############################
 
 The documentation of type definitions, typedefs for short, is a simple
-but tricky matter. Typedefs are aliases for other types and as such
+yet tricky matter. Typedefs are aliases for other types and, as such,
 need to be well documented. Always document typedefs even if the
 complex type it uses is documented already.
 
-Type Definition Comment Template.
-*********************************
+Type Definition Comment Template
+********************************
 
 Typedefs require a simple comment explaining why they are being used and
 what type they are referencing.
@@ -19,10 +19,9 @@ what type they are referencing.
    /** Brief description with the type that is being used and why. */
    typedef int t_ie;
 
-No further explanation is needed regarding the type even if it is
-complex. Each complex type must be documented where ever it was
-defined. Doxygen connects the typedef and the complex type it uses
-automatically.
+No further explanation is needed regarding the type even if it is complex.
+Each complex type must be documented whereever it was defined.
+Doxygen connects the typedef and the complex type it uses automatically.
 
 Type Definition Documentation Example
 *************************************
@@ -49,8 +48,8 @@ Incorrect:
    :emphasize-lines: 3, 4
    :linenos:
 
-The comments on lines 3 and 4 offer little insight into the code's
-behavior. Furthermore, they do not start with
+The comments on lines 3 and 4 offer little insight into the code's behavior.
+Furthermore, they do not start with
 :literal:`/**` and end with :literal:`*/`. Doxygen won't add the
 information to the documentation nor link it properly to the complex
 type documentation.