[Docs] Improve and unify Doxygen comments, part 1

Signed-off-by: Michał Kowalczyk <mkow@invisiblethingslab.com>

Documentation/devel/howto-doc.rst

@@ -150,19 +150,23 @@ Preferred Doxygen style
 
 #. Prefer Qt-style ``/*!`` and ``\param``:
 
+   .. Note that the snippet below is wrapped to 106 chars per line. This is
+      because it quotes C code (wrapped to 100), and the quote is itself
+      indented in reST.
+
    .. code-block:: c
 
       /*!
-       * \brief An example function
+       * \brief Sum two integers.
        *
-       * This function returns a number augmented by the Answer to the Ultimate
-       * Question of Life, the Universe, and Everything.
+       * \param first   First addend.
+       * \param second  Second addend.
        *
-       * \param n The number to be added
-       * \return A number 42 greater
+       * \returns Sum of the arguments. Sometimes a longer description is needed, then it should be
+       *          wrapped and aligned like this.
        */
-      int foo(int n) {
-          return n + 42;
+      int foo(int first, int second) {
+          return first + second;
       }
 
    ::

LibOS/shim/include/shim_checkpoint.h

@@ -349,14 +349,14 @@ typedef int (*migrate_func_t)(struct shim_cp_store*, struct shim_process*, struc
  *
  * Called in parent process during fork/clone.
  *
- * \param migrate_func          Migration function defined by the caller.
- * \param child_process         Struct bookkeeping the child process, added to the children list.
- * \param process_description   Struct describing the new process (child).
- * \param thread_description    Struct describing main thread of the child process.
+ * \param migrate_func         Migration function defined by the caller.
+ * \param child_process        Struct bookkeeping the child process, added to the children list.
+ * \param process_description  Struct describing the new process (child).
+ * \param thread_description   Struct describing main thread of the child process.
  *
  * The remaining arguments are passed into the migration function.
  *
- * \return  0 on success, negative POSIX error code on failure.
+ * \returns 0 on success, negative POSIX error code on failure.
  */
 int create_process_and_send_checkpoint(migrate_func_t migrate_func,
                                        struct shim_child_process* child_process,
@@ -368,9 +368,9 @@ int create_process_and_send_checkpoint(migrate_func_t migrate_func,
  *
  * Called in child process during initialization.
  *
- * \param[in] hdr  Checkpoint header already received from the parent.
+ * \param hdr  Checkpoint header already received from the parent.
  *
- * \return         0 on success, negative POSIX error code on failure.
+ * \returns 0 on success, negative POSIX error code on failure.
  */
 int receive_checkpoint_and_restore(struct checkpoint_hdr* hdr);