Doxygen comment update and PREDEFINED in Doxyfile is properly defined (#5186)

JerryScript-DCO-1.0-Signed-off-by: Yonggang Luo luoyonggang@gmail.com
2024-12-17 16:02:54 +08:00
parent 718a439db1
commit 5480cc3973
19 changed files with 17 additions and 87 deletions
@@ -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)
@@ -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 */
@@ -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 */
@@ -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 */
@@ -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;
@@ -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 */
@@ -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 */
@@ -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 */
@@ -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 */
@@ -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 */
@@ -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 */
@@ -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);

@@ -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 */
@@ -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 */
@@ -114,8 +114,6 @@ jmem_pools_alloc (size_t size) /**< size of the chunk */

 /**
 * Free the chunk
- *
- * @return void
 */
 extern inline void JERRY_ATTR_HOT JERRY_ATTR_ALWAYS_INLINE
 jmem_pools_free (void *chunk_p, /**< pointer to the chunk */
@@ -1189,8 +1189,6 @@ opfunc_create_implicit_class_constructor (uint8_t opcode, /**< current cbc opcod

 /**
 * Set the [[HomeObject]] attribute of the given functon object
- *
- * @return void
 */
 extern inline void JERRY_ATTR_ALWAYS_INLINE
 opfunc_set_home_object (ecma_object_t *func_p, /**< function object */
@@ -5137,9 +5137,6 @@ JERRY_STATIC_ASSERT ((int) CBC_CODE_FLAGS_STRICT_MODE == (int) VM_FRAME_CTX_IS_S

 /**
 * Initialize code block execution
- *
- * @return ECMA_VALUE_ERROR - if the initialization fails
- *         ECMA_VALUE_EMPTY - otherwise
 */
 static void JERRY_ATTR_NOINLINE
 vm_init_exec (vm_frame_ctx_t *frame_ctx_p) /**< frame context */