Doxygen comment update and PREDEFINED in Doxyfile is properly defined (…

…#5186) JerryScript-DCO-1.0-Signed-off-by: Yonggang Luo [email protected]
jerryscript-project · Dec 17, 2024 · 5480cc3 · 5480cc3
1 parent 718a439
commit 5480cc3
Show file tree

Hide file tree

Showing 19 changed files with 17 additions and 87 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -2216,7 +2216,14 @@ INCLUDE_FILE_PATTERNS  =
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
 PREDEFINED             = "JERRY_STATIC_ASSERT(x,y)=" \
-                         "JERRY_ATTR_FORMAT(x,y,z)="
+                         "JERRY_ATTR_FORMAT(x,y,z)=" \
+                         "JERRY_ATTR_ALWAYS_INLINE=" \
+                         "JERRY_ATTR_NOINLINE=" \
+                         "JERRY_ATTR_PURE=" \
+                         "JERRY_ATTR_CONST=" \
+                         "JERRY_ATTR_HOT=" \
+                         "JERRY_ATTR_NORETURN=" \
+                         "JERRY_ATTR_WEAK="
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

diff --git a/jerry-core/api/jerryscript.c b/jerry-core/api/jerryscript.c
@@ -115,8 +115,6 @@ 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)
@@ -126,8 +124,6 @@ jerry_assert_api_enabled (void)
 
 /**
  * Turn on API availability
- *
- * @return void
  */
 static inline void JERRY_ATTR_ALWAYS_INLINE
 jerry_api_enable (void)
@@ -139,8 +135,6 @@ jerry_api_enable (void)
 
 /**
  * Turn off API availability
- *
- * @return void
  */
 static inline void JERRY_ATTR_ALWAYS_INLINE
 jerry_api_disable (void)

diff --git a/jerry-core/ecma/base/ecma-alloc.c b/jerry-core/ecma/base/ecma-alloc.c
@@ -61,8 +61,6 @@ 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 */
@@ -87,8 +85,6 @@ 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 */
@@ -117,8 +113,6 @@ 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 */
@@ -148,8 +142,6 @@ 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 */
@@ -178,8 +170,6 @@ 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 */
@@ -208,8 +198,6 @@ 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 */
@@ -238,8 +226,6 @@ 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 */
@@ -269,8 +255,6 @@ 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 */

diff --git a/jerry-core/ecma/base/ecma-gc.c b/jerry-core/ecma/base/ecma-gc.c
@@ -128,8 +128,6 @@ 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 */
@@ -155,8 +153,6 @@ 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 */
@@ -470,8 +466,6 @@ 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 */

diff --git a/jerry-core/ecma/base/ecma-helpers-collection.c b/jerry-core/ecma/base/ecma-helpers-collection.c
@@ -49,8 +49,6 @@ 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 */

diff --git a/jerry-core/ecma/base/ecma-helpers-conversion.c b/jerry-core/ecma/base/ecma-helpers-conversion.c
@@ -52,7 +52,7 @@ typedef struct
  * @return rounded high to uint64_t
  */
 static uint64_t
-ecma_round_high_to_uint64 (ecma_uint128_t *num_p)
+ecma_round_high_to_uint64 (ecma_uint128_t *num_p) /**< 128-bit unsigned integer */
 {
   uint64_t masked_lo = num_p->lo & ~(1ULL << 63u);
   uint64_t masked_hi = num_p->hi & 0x1;
@@ -69,7 +69,8 @@ ecma_round_high_to_uint64 (ecma_uint128_t *num_p)
  * Left shift 128-bit integer by max 63 bits.
  */
 static void JERRY_ATTR_ALWAYS_INLINE
-ecma_uint128_shift_left (ecma_uint128_t *num_p, int32_t shift)
+ecma_uint128_shift_left (ecma_uint128_t *num_p, /**< 128-bit unsigned integer */
+                         int32_t shift) /**< left shift count */
 {
   num_p->hi = (num_p->hi << shift) | (num_p->lo >> (64 - shift));
   num_p->lo <<= shift;
@@ -79,7 +80,8 @@ ecma_uint128_shift_left (ecma_uint128_t *num_p, int32_t shift)
  * Right shift 128-bit integer by max 63 bits.
  */
 static void JERRY_ATTR_ALWAYS_INLINE
-ecma_uint128_shift_right (ecma_uint128_t *num_p, int32_t shift)
+ecma_uint128_shift_right (ecma_uint128_t *num_p, /**< 128-bit unsigned integer */
+                          int32_t shift) /**< right shift count */
 {
   num_p->lo = (num_p->lo >> shift) | (num_p->hi << (64 - shift));
   num_p->hi >>= shift;
@@ -89,7 +91,8 @@ ecma_uint128_shift_right (ecma_uint128_t *num_p, int32_t shift)
  * Add two 128-bit integer values and assign the result to the left one.
  */
 static void
-ecma_uint128_add (ecma_uint128_t *left_p, ecma_uint128_t *right_p)
+ecma_uint128_add (ecma_uint128_t *left_p, /**< left 128-bit unsigned integer */
+                  ecma_uint128_t *right_p) /**< right 128-bit unsigned integer */
 {
   left_p->hi += right_p->hi;
   left_p->lo += right_p->lo;
@@ -104,7 +107,7 @@ ecma_uint128_add (ecma_uint128_t *left_p, ecma_uint128_t *right_p)
  * Multiply 128-bit integer by 10
  */
 static void
-ecma_uint128_mul10 (ecma_uint128_t *num_p)
+ecma_uint128_mul10 (ecma_uint128_t *num_p) /**< 128-bit unsigned integer */
 {
   ecma_uint128_shift_left (num_p, 1u);
 
@@ -130,7 +133,7 @@ ecma_uint128_mul10 (ecma_uint128_t *num_p)
  * Q = Q3 *2^96  + Q2 *2^64  + Q1 *2^32  + Q0 *2^0     // 128-bit quotient
  */
 static void
-ecma_uint128_div10 (ecma_uint128_t *num_p)
+ecma_uint128_div10 (ecma_uint128_t *num_p) /**< 128-bit unsigned integer */
 {
   /* estimation of reciprocal of 10, 128 bits right of the binary point (T1 == T2) */
   const uint64_t tenth_l = 0x9999999aul;

diff --git a/jerry-core/ecma/base/ecma-helpers-errol.c b/jerry-core/ecma/base/ecma-helpers-errol.c
@@ -78,8 +78,6 @@ 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 */
@@ -92,8 +90,6 @@ 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 */

diff --git a/jerry-core/ecma/base/ecma-helpers-string.c b/jerry-core/ecma/base/ecma-helpers-string.c
@@ -849,8 +849,6 @@ 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 */
@@ -897,8 +895,6 @@ 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 */
@@ -1172,8 +1168,6 @@ 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 */
@@ -2298,8 +2292,6 @@ 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 */

diff --git a/jerry-core/ecma/base/ecma-helpers-value.c b/jerry-core/ecma/base/ecma-helpers-value.c
@@ -939,8 +939,6 @@ 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 */
@@ -953,8 +951,6 @@ 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 */
@@ -1140,8 +1136,6 @@ 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 */
@@ -1166,8 +1160,6 @@ 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 */
@@ -1177,8 +1169,6 @@ 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 */

diff --git a/jerry-core/ecma/base/ecma-helpers.c b/jerry-core/ecma/base/ecma-helpers.c
@@ -917,8 +917,6 @@ 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 */

diff --git a/jerry-core/ecma/operations/ecma-objects.c b/jerry-core/ecma/operations/ecma-objects.c
@@ -3258,8 +3258,6 @@ 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 */

diff --git a/jerry-core/ecma/operations/ecma-promise-object.c b/jerry-core/ecma/operations/ecma-promise-object.c
@@ -68,8 +68,6 @@ 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 */
@@ -99,8 +97,6 @@ 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 */

diff --git a/jerry-core/include/jerryscript-port.h b/jerry-core/include/jerryscript-port.h
@@ -61,7 +61,6 @@ void jerry_port_init (void);
  * A libc-based port may implement this with exit() or abort(), or both.
  *
  * @param code: the cause of the error.
- * @return This function is expected to not return.
  */
 void JERRY_ATTR_NORETURN jerry_port_fatal (jerry_fatal_code_t code);
 

diff --git a/jerry-core/jcontext/jcontext.c b/jerry-core/jcontext/jcontext.c
@@ -45,8 +45,6 @@ jcontext_has_pending_abort (void)
 
 /**
  * Set the abort flag for the context.
- *
- * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 jcontext_set_abort_flag (bool is_abort) /**< true - if the abort flag should be set
@@ -66,8 +64,6 @@ jcontext_set_abort_flag (bool is_abort) /**< true - if the abort flag should be
 
 /**
  * Set the exception flag for the context.
- *
- * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 jcontext_set_exception_flag (bool is_exception) /**< true - if the exception flag should be set
@@ -85,8 +81,6 @@ jcontext_set_exception_flag (bool is_exception) /**< true - if the exception fla
 
 /**
  * Raise exception from the given error value.
- *
- * @return void
  */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 jcontext_raise_exception (ecma_value_t error) /**< error to raise */

diff --git a/jerry-core/jmem/jmem-heap.c b/jerry-core/jmem/jmem-heap.c
@@ -459,8 +459,6 @@ jmem_heap_insert_block (jmem_heap_free_t *block_p, /**< block to insert */
 
 /**
  * Internal method for freeing a memory block.
- *
- * @return void
  */
 void JERRY_ATTR_HOT
 jmem_heap_free_block_internal (void *ptr, /**< pointer to beginning of data space of the block */
@@ -695,8 +693,6 @@ jmem_heap_realloc_block (void *ptr, /**< memory region to reallocate */
 
 /**
  * Free memory block
- *
- * @return void
  */
 extern inline void JERRY_ATTR_HOT JERRY_ATTR_ALWAYS_INLINE
 jmem_heap_free_block (void *ptr, /**< pointer to beginning of data space of the block */