Update doxygen and fix documentation (#5106)

Update Doxyfile to version 1.9.1

Re-enable doxygen CI checker

Fix some regular comments that should have been doc comments

Document void return types for some inline functions explicitly

Move start of some doxygen groups so they are included always, and not left
out of certain ifdefs

Ignore some doxygen warnings:
    Member (function) is not documented in headers
    Documented empty return type in headers
    Argument has multiple @param documentation sections

JerryScript-DCO-1.0-Signed-off-by: Máté Tokodi [email protected]

.github/workflows/gh-actions.yml

@@ -17,12 +17,12 @@ jobs:
           python-version: '3.10'
       - run: sudo apt update
 # TODO: update checkers to current versions available in ubuntu 22.04
-#      - run: sudo apt install doxygen clang-format-10 cppcheck python-serial
-      - run: sudo apt install pylint
+#      - run: sudo apt install clang-format-10 cppcheck python-serial
+      - run: sudo apt install pylint doxygen
       - run: $RUNNER --check-signed-off=gh-actions
         if: ${{ always() }}
-#      - run: $RUNNER --check-doxygen
-#        if: ${{ always() }}
+      - run: $RUNNER --check-doxygen
+        if: ${{ always() }}
 #      - run: $RUNNER --check-format
 #        if: ${{ always() }}
       - run: $RUNNER --check-license

jerry-core/api/jerry-snapshot.c

@@ -31,6 +31,10 @@
 #include "lit-char-helpers.h"
 #include "re-compiler.h"
 
+/** \addtogroup jerrysnapshot Jerry snapshot operations
+ * @{
+ */
+
 #if JERRY_SNAPSHOT_SAVE || JERRY_SNAPSHOT_EXEC
 
 /**
@@ -88,9 +92,6 @@ typedef struct
   bool class_found;
 } snapshot_globals_t;
 
-/** \addtogroup jerrysnapshot Jerry snapshot operations
- * @{
- */
 
 /**
  * Write data into the specified buffer.
@@ -1045,10 +1046,6 @@ jerry_exec_snapshot (const uint32_t *snapshot_p, /**< snapshot */
 #endif /* JERRY_SNAPSHOT_EXEC */
 } /* jerry_exec_snapshot */
 
-/**
- * @}
- */
-
 #if JERRY_SNAPSHOT_SAVE
 
 /**
@@ -1716,3 +1713,7 @@ jerry_get_literals_from_snapshot (const uint32_t *snapshot_p, /**< input snapsho
   return 0;
 #endif /* JERRY_SNAPSHOT_SAVE */
 } /* jerry_get_literals_from_snapshot */
+
+/**
+ * @}
+ */

jerry-core/api/jerryscript.c

@@ -115,6 +115,8 @@ JERRY_STATIC_ASSERT (((NUMBER_ARITHMETIC_SUBTRACTION + ECMA_NUMBER_ARITHMETIC_OP
  *         The API could not be invoked in the following cases:
  *           - before jerry_init and after jerry_cleanup
  *           - between enter to and return from a native free callback
+ *
+ * @return void
  */
 static inline void JERRY_ATTR_ALWAYS_INLINE
 jerry_assert_api_enabled (void)
@@ -124,6 +126,8 @@ jerry_assert_api_enabled (void)
 
 /**
  * Turn on API availability
+ *
+ * @return void
  */
 static inline void JERRY_ATTR_ALWAYS_INLINE
 jerry_api_enable (void)
@@ -135,6 +139,8 @@ jerry_api_enable (void)
 
 /**
  * Turn off API availability
+ *
+ * @return void
  */
 static inline void JERRY_ATTR_ALWAYS_INLINE
 jerry_api_disable (void)

jerry-core/ecma/base/ecma-alloc.c

@@ -61,6 +61,8 @@ ecma_alloc_number (void)
 
 /**
  * Dealloc memory from an ecma-number
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_dealloc_number (ecma_number_t *number_p) /**< number to be freed */
@@ -85,6 +87,8 @@ ecma_alloc_object (void)
 
 /**
  * Dealloc memory from an ecma-object
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_dealloc_object (ecma_object_t *object_p) /**< object to be freed */
@@ -113,6 +117,8 @@ ecma_alloc_extended_object (size_t size) /**< size of object */
 
 /**
  * Dealloc memory of an extended object
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_dealloc_extended_object (ecma_object_t *object_p, /**< extended object */
@@ -142,6 +148,8 @@ ecma_alloc_string (void)
 
 /**
  * Dealloc memory from ecma-string descriptor
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_dealloc_string (ecma_string_t *string_p) /**< string to be freed */
@@ -170,6 +178,8 @@ ecma_alloc_extended_string (void)
 
 /**
  * Dealloc memory from extended ecma-string descriptor
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_dealloc_extended_string (ecma_extended_string_t *ext_string_p) /**< extended string to be freed */
@@ -198,6 +208,8 @@ ecma_alloc_external_string (void)
 
 /**
  * Dealloc memory from external ecma-string descriptor
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_dealloc_external_string (ecma_external_string_t *ext_string_p) /**< external string to be freed */
@@ -226,6 +238,8 @@ ecma_alloc_string_buffer (size_t size) /**< size of string */
 
 /**
  * Dealloc memory of a string with character data
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_dealloc_string_buffer (ecma_string_t *string_p, /**< string with data */
@@ -255,6 +269,8 @@ ecma_alloc_property_pair (void)
 
 /**
  * Dealloc memory of an ecma-property
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_dealloc_property_pair (ecma_property_pair_t *property_pair_p) /**< property pair to be freed */

jerry-core/ecma/base/ecma-gc.c

@@ -128,6 +128,8 @@ ecma_init_gc_info (ecma_object_t *object_p) /**< object */
 
 /**
  * Increase reference counter of an object
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_ref_object_inline (ecma_object_t *object_p) /**< object */
@@ -153,6 +155,8 @@ ecma_ref_object (ecma_object_t *object_p) /**< object */
 
 /**
  * Decrease reference counter of an object
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_deref_object (ecma_object_t *object_p) /**< object */
@@ -466,6 +470,8 @@ ecma_gc_mark_compiled_code (ecma_value_t script_value) /**< script value */
 
 /**
  * Mark objects referenced by bound function object.
+ *
+ * @return void
  */
 static void JERRY_ATTR_NOINLINE
 ecma_gc_mark_bound_function_object (ecma_object_t *object_p) /**< bound function object */

jerry-core/ecma/base/ecma-helpers-collection.c

@@ -49,6 +49,8 @@ ecma_new_collection (void)
 
 /**
  * Deallocate a collection of ecma values without freeing it's values
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_collection_destroy (ecma_collection_t *collection_p) /**< value collection */

jerry-core/ecma/base/ecma-helpers-errol.c

@@ -78,6 +78,8 @@ typedef struct
 
 /**
  * Normalize the number by factoring in the error.
+ *
+ * @return void
  */
 static inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_normalize_high_prec_data (ecma_high_prec_t *hp_data_p) /**< [in, out] float pair */
@@ -90,6 +92,8 @@ ecma_normalize_high_prec_data (ecma_high_prec_t *hp_data_p) /**< [in, out] float
 
 /**
  * Multiply the high-precision number by ten.
+ *
+ * @return void
  */
 static inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_multiply_high_prec_by_10 (ecma_high_prec_t *hp_data_p) /**< [in, out] high-precision number */

jerry-core/ecma/base/ecma-helpers-string.c

@@ -849,6 +849,8 @@ ecma_concat_ecma_strings (ecma_string_t *string1_p, /**< first ecma-string */
 
 /**
  * Increase reference counter of non-direct ecma-string.
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_ref_ecma_string_non_direct (ecma_string_t *string_p) /**< string descriptor */
@@ -895,6 +897,8 @@ ecma_ref_ecma_string (ecma_string_t *string_p) /**< string descriptor */
 /**
  * Decrease reference counter and deallocate a non-direct ecma-string
  * if the counter becomes zero.
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_deref_ecma_string_non_direct (ecma_string_t *string_p) /**< ecma-string */
@@ -1168,6 +1172,8 @@ ecma_string_copy_to_buffer (const ecma_string_t *string_p, /**< ecma-string desc
  * Convert ecma-string's contents to a cesu-8 string and put it to the buffer.
  * It is the caller's responsibility to make sure that the string fits in the buffer.
  * Check if the size of the string is equal with the size of the buffer.
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_string_to_cesu8_bytes (const ecma_string_t *string_desc_p, /**< ecma-string descriptor */
@@ -2292,6 +2298,8 @@ ecma_string_trim_back (const lit_utf8_byte_t *start_p, /**< current string's sta
  * Used by:
  *        - ecma_string_trim
  *        - ecma_utf8_string_to_number
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_string_trim_helper (const lit_utf8_byte_t **utf8_str_p, /**< [in, out] current string position */

jerry-core/ecma/base/ecma-helpers-value.c

@@ -939,6 +939,8 @@ ecma_copy_value_if_not_object (ecma_value_t value) /**< value description */
 
 /**
  * Increase reference counter of a value if it is an object.
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_ref_if_object (ecma_value_t value) /**< value description */
@@ -951,6 +953,8 @@ ecma_ref_if_object (ecma_value_t value) /**< value description */
 
 /**
  * Decrease reference counter of a value if it is an object.
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_deref_if_object (ecma_value_t value) /**< value description */
@@ -1136,6 +1140,8 @@ ecma_free_value (ecma_value_t value) /**< value description */
  *   faster for direct values since no function call is performed.
  *   It also increases the binary size so it is recommended for
  *   critical code paths only.
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_fast_free_value (ecma_value_t value) /**< value description */
@@ -1160,6 +1166,8 @@ ecma_free_value_if_not_object (ecma_value_t value) /**< value description */
 
 /**
  * Free an ecma-value object
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_free_object (ecma_value_t value) /**< value description */
@@ -1169,6 +1177,8 @@ ecma_free_object (ecma_value_t value) /**< value description */
 
 /**
  * Free an ecma-value number
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_free_number (ecma_value_t value) /**< value description */

jerry-core/ecma/base/ecma-helpers.c

@@ -917,6 +917,8 @@ ecma_assert_object_contains_the_property (const ecma_object_t *object_p, /**< ec
  *
  * Note:
  *      value previously stored in the property is freed
+ *
+ * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_named_data_property_assign_value (ecma_object_t *obj_p, /**< object */

jerry-core/ecma/base/ecma-line-info.c

@@ -17,15 +17,15 @@
 
 #include "ecma-helpers.h"
 
-#if JERRY_LINE_INFO
-
 /** \addtogroup ecma ECMA
  * @{
  *
  * \addtogroup ecmalineinfo Line info
  * @{
  */
 
+#if JERRY_LINE_INFO
+
 /* The layout of the structure is defined in js-parser-line-info-create.c */
 
 JERRY_STATIC_ASSERT ((ECMA_LINE_INFO_COLUMN_DEFAULT - 1) == ((ECMA_LINE_INFO_ENCODE_TWO_BYTE >> 1) - 1),

jerry-core/ecma/builtin-objects/ecma-builtin-helpers-json.c

@@ -55,9 +55,9 @@ ecma_json_has_object_in_stack (ecma_json_occurrence_stack_item_t *stack_p, /**<
   return false;
 } /* ecma_json_has_object_in_stack */
 
-#endif /* JERRY_BUILTIN_JSON */
-
 /**
  * @}
  * @}
  */
+
+#endif /* JERRY_BUILTIN_JSON */

jerry-core/ecma/builtin-objects/ecma-builtin-helpers.h

@@ -261,7 +261,8 @@ ecma_value_t ecma_builtin_helper_error_dispatch_call (jerry_error_t error_type,
 typedef ecma_value_t (*ecma_builtin_helper_sort_compare_fn_t) (ecma_value_t lhs, /**< left value */
                                                                ecma_value_t rhs, /**< right value */
                                                                ecma_value_t compare_func, /**< compare function */
-                                                               ecma_object_t *array_buffer_p); /**< arrayBuffer */
+                                                               ecma_object_t *array_buffer_p /**< arrayBuffer */
+                                                               );
 
 ecma_value_t ecma_builtin_helper_array_merge_sort_helper (ecma_value_t *array_p,
                                                           uint32_t length,

jerry-core/ecma/operations/ecma-objects.c

@@ -3267,6 +3267,8 @@ ecma_op_ordinary_object_is_extensible (ecma_object_t *object_p) /**< object */
 
 /**
  * Set value of [[Extensible]] object's internal property.
+ *
+ * @return void
  */
 void JERRY_ATTR_NOINLINE
 ecma_op_ordinary_object_prevent_extensions (ecma_object_t *object_p) /**< object */

jerry-core/ecma/operations/ecma-promise-object.c

@@ -68,6 +68,8 @@ ecma_promise_get_result (ecma_object_t *obj_p) /**< points to promise object */
 
 /**
  * Set the PromiseResult of promise.
+ *
+ * @return void
  */
 static inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_promise_set_result (ecma_object_t *obj_p, /**< points to promise object */
@@ -97,6 +99,8 @@ ecma_promise_get_flags (ecma_object_t *obj_p) /**< points to promise object */
 
 /**
  * Set the PromiseState of promise.
+ *
+ * @return void
  */
 static inline void JERRY_ATTR_ALWAYS_INLINE
 ecma_promise_set_state (ecma_object_t *obj_p, /**< points to promise object */

jerry-core/ecma/operations/ecma-shared-arraybuffer-object.h

@@ -18,15 +18,15 @@
 
 #include "ecma-globals.h"
 
-#if JERRY_BUILTIN_SHAREDARRAYBUFFER
-
 /** \addtogroup ecma ECMA
  * @{
  *
  * \addtogroup ecmasharedarraybufferobject ECMA SharedArrayBuffer object related routines
  * @{
  */
 
+#if JERRY_BUILTIN_SHAREDARRAYBUFFER
+
 ecma_value_t ecma_op_create_shared_arraybuffer_object (const ecma_value_t *, uint32_t);
 
 /**

jerry-core/ecma/operations/ecma-string-object.c

@@ -98,8 +98,6 @@ ecma_op_create_string_object (const ecma_value_t *arguments_list_p, /**< list of
 
 /**
  * List names of a String object's lazy instantiated properties
- *
- * @return string values collection
  */
 void
 ecma_op_string_list_lazy_property_names (ecma_object_t *obj_p, /**< a String object */