DOC: Apply suggestions from Matti review

Co-authored-by: Matti Picus <matti.picus@gmail.com>

1 files changed, 17 insertions, 14 deletions

diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst
index 501de9e1c..f8513aced 100644
--- a/doc/source/dev/howto-docs.rst
+++ b/doc/source/dev/howto-docs.rst
@@ -215,15 +215,13 @@ Note that for documentation within NumPy, it is not necessary to do
 Please use the ``numpydoc`` :ref:`formatting standard <numpydoc:format>` as
 shown in their :ref:`example <numpydoc:example>`.
 
-.. _doc_c_cpp:
+.. _doc_c_code:
 
 Documenting C/C++ Code
 ======================
 
-Recently, NumPy headed out to use Doxygen_ along with Sphinx due to the urgent need
-to generate C/C++ API reference documentation from comment blocks, especially with
-the most recent expansion in the use of SIMD, and also due to the future reliance on C++.
-Thanks to Breathe_, we were able to bind both worlds together at the lowest cost.
+NumPy uses Doxygen_ to parse specially-formatted C/C++ comment blocks. This generates
+XML files, which are  converted by Breathe_ into RST, which is used by Sphinx.
 
 **It takes three steps to complete the documentation process**:
 
@@ -235,10 +233,9 @@ is more preferable than the others due to the similarities with the current
 existing non-indexed comment blocks.
 
 .. note::
-   If you have never used Doxygen_ before, then maybe you need to take a quick
-   look at `"Documenting the code" <https://www.doxygen.nl/manual/docblocks.html>`__.
+   Please see `"Documenting the code" <https://www.doxygen.nl/manual/docblocks.html>`__.
 
-This is how Javadoc style looks like::
+This is what Javadoc style looks like::
 
   /**
    * Your brief is here.
@@ -252,7 +249,7 @@ For line comment, insert a triple forward slash::
 
 And for structured data members, just insert triple forward slash and less-than sign::
 
-  /// Data type brief.
+  /// Data type brief description
   typedef struct {
       int member_1; ///< Member 1 description.
       int member_2; ///< Member 2 description.
@@ -297,10 +294,16 @@ It is interpreted as source code.
 
 ``@rst/@endrst``
 
-Starts/Ends a block of reST markup. Take a look at the following example:
+Starts/Ends a block of reST markup.
+
+Example
+~~~~~~~
+Take a look at the following example:
 
 .. literalinclude:: examples/doxy_rst.h
 
+And here is how it is rendered:
+
 .. doxygenfunction:: doxy_reST_example
 
 2. Feeding Doxygen
@@ -311,11 +314,11 @@ C/C++ header paths within the sub-config files of Doxygen.
 
 Sub-config files have the unique name ``.doxyfile``, which you can usually find near
 directories that contain documented headers. You need to create a new config file if
-there's no one located in a path close(2-depth) to the headers you want to add.
+there's not one located in a path close(2-depth) to the headers you want to add.
 
 Sub-config files can accept any of Doxygen_ `configuration options <https://www.doxygen.nl/manual/config.html>`__,
-but you should be aware of not overriding or re-initializing any configuration option,
-you must only count on the concatenation operator "+=". For example::
+but do not override or re-initialize any configuration option,
+rather only use the concatenation operator "+=". For example::
 
    # to specfiy certain headers
    INPUT += @CUR_DIR/header1.h \
@@ -336,7 +339,7 @@ you must only count on the concatenation operator "+=". For example::
 -----------------------
 
 Breathe_ provides a wide range of custom directives to allow
-including the generated documents by Doxygen_ into reST files.
+converting the documents generated by Doxygen_ into reST files.
 
 .. note::
    For more information, please check out "`Directives & Config Variables <https://breathe.readthedocs.io/en/latest/directives.html>`__"