DOC: Improve Doxygen Javadoc style examples

3 files changed, 43 insertions, 16 deletions

diff --git a/doc/source/dev/examples/doxy_class.hpp b/doc/source/dev/examples/doxy_class.hpp
new file mode 100644
index 000000000..ceba63487
--- /dev/null
+++ b/doc/source/dev/examples/doxy_class.hpp
@@ -0,0 +1,21 @@
+/**
+ *  Template to represent limbo numbers.
+ *
+ *  Specializations for integer types that are part of nowhere.
+ *  It doesn't support with any real types.
+ *
+ *  @param Tp Type of the integer. Required to be an integer type.
+ *  @param N  Number of elements.
+*/
+template<typename Tp, std::size_t N>
+class DoxyLimbo {
+ public:
+    /// Default constructor. Initialize nothing.
+    DoxyLimbo();
+    /// Set Default behavior for copy the limbo.
+    DoxyLimbo(const DoxyLimbo<Tp, N> &l);
+    /// Returns the raw data for the limbo.
+    const Tp *data();
+ protected:
+    Tp p_data[N]; ///< Example for inline comment.
+};
diff --git a/doc/source/dev/examples/doxy_func.h b/doc/source/dev/examples/doxy_func.h
new file mode 100644
index 000000000..792a9d1b7
--- /dev/null
+++ b/doc/source/dev/examples/doxy_func.h
@@ -0,0 +1,11 @@
+/**
+ * This a simple brief.
+ *
+ * And the details goes here.
+ * Multi lines are welcome.
+ *
+ * @param  num  leave a comment for parameter num.
+ * @param  str  leave a comment for the second parameter.
+ * @return      leave a comment for the returned value.
+ */
+int doxy_javadoc_example(int num, const char *str);
diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst
index f8513aced..cc17a1feb 100644
--- a/doc/source/dev/howto-docs.rst
+++ b/doc/source/dev/howto-docs.rst
@@ -235,26 +235,21 @@ existing non-indexed comment blocks.
 .. note::
    Please see `"Documenting the code" <https://www.doxygen.nl/manual/docblocks.html>`__.
 
-This is what Javadoc style looks like::
+**This is what Javadoc style looks like**:
 
-  /**
-   * Your brief is here.
-   */
-  void function(void);
+.. literalinclude:: examples/doxy_func.h
 
-For line comment, insert a triple forward slash::
+**And here is how it is rendered**:
 
-  /// Your brief is here.
-  void function(void);
+.. doxygenfunction:: doxy_javadoc_example
 
-And for structured data members, just insert triple forward slash and less-than sign::
+**For line comment, you can use a triple forward slash. For example**:
 
-  /// Data type brief description
-  typedef struct {
-      int member_1; ///< Member 1 description.
-      int member_2; ///< Member 2 description.
-  } data_type;
+.. literalinclude:: examples/doxy_class.hpp
 
+**And here is how it is rendered**:
+
+.. doxygenclass:: DoxyLimbo
 
 Common Doxygen Tags:
 ++++++++++++++++++++
@@ -298,11 +293,11 @@ Starts/Ends a block of reST markup.
 
 Example
 ~~~~~~~
-Take a look at the following example:
+**Take a look at the following example**:
 
 .. literalinclude:: examples/doxy_rst.h
 
-And here is how it is rendered:
+**And here is how it is rendered**:
 
 .. doxygenfunction:: doxy_reST_example