From 9aca0086b960db0e46ba0c54895fd5d3230fad9c Mon Sep 17 00:00:00 2001 From: Akos Kiss Date: Sat, 9 Apr 2016 21:27:43 +0200 Subject: [PATCH] Doc comment maintenance Fixed doc comments issues: * Fixed mistyped param doc comments (`/**<` is OK, `/** <` is not). * Put special characters (e.g., pipe, backslash, etc.) in quotes, as they can confuse doxygen and it will print lots of various warnings. For the sake of completeness and consistent style, also quote some special characters in re-bytecode.h * Added missing `@{`s, removed extra `@}`s. * Turned `/*` comments to `/**<` doc comments. Ensured same style for doc groups everywhere: * Where `\addtogroup`, `@{`, and `@}` doxygen commands are used, the order to be followed is: license, `#ifndef` guards (in headers), includes, `\addtogroup` and `@{`, main code content, `@}`, `#endif` guards (in headers). * Multiple `\addtogroup`s or multiple `@}`s should be in the same doc comment. * First `\addtogroup` should be on the very first line of a doc comment, i.e., `/** \addtogroup`. JerryScript-DCO-1.0-Signed-off-by: Akos Kiss akiss@inf.u-szeged.hu --- jerry-core/ecma/base/ecma-alloc.h | 17 ++++---- jerry-core/ecma/base/ecma-gc.c | 14 +++---- jerry-core/ecma/base/ecma-gc.h | 18 ++++----- jerry-core/ecma/base/ecma-globals.h | 21 ++++------ .../ecma/base/ecma-helpers-conversion.c | 14 +++---- .../base/ecma-helpers-external-pointers.c | 8 ++-- jerry-core/ecma/base/ecma-helpers-number.c | 6 +-- jerry-core/ecma/base/ecma-helpers-string.c | 24 +++++------ jerry-core/ecma/base/ecma-helpers-value.c | 14 +++---- .../base/ecma-helpers-values-collection.c | 10 ++--- jerry-core/ecma/base/ecma-helpers.c | 14 +++---- jerry-core/ecma/base/ecma-helpers.h | 18 ++++----- jerry-core/ecma/base/ecma-init-finalize.h | 4 +- .../ecma-builtin-helpers-json.c | 12 +++--- .../builtin-objects/ecma-builtin-helpers.c | 2 +- jerry-core/ecma/operations/ecma-eval.c | 1 + jerry-core/ecma/operations/ecma-eval.h | 1 + jerry-core/ecma/operations/ecma-exceptions.c | 6 +-- jerry-core/ecma/operations/ecma-exceptions.h | 6 +-- jerry-core/ecma/operations/ecma-lex-env.c | 8 +--- jerry-core/ecma/operations/ecma-lex-env.h | 10 ++--- .../ecma/operations/ecma-number-arithmetic.c | 4 +- .../ecma/operations/ecma-number-arithmetic.h | 4 +- .../ecma/operations/ecma-objects-arguments.c | 14 +++---- jerry-core/ecma/operations/ecma-reference.c | 4 +- jerry-core/ecma/operations/ecma-reference.h | 6 +-- jerry-core/mem/mem-allocator.c | 1 - jerry-core/mem/mem-allocator.h | 12 +++--- jerry-core/mem/mem-heap.c | 15 ++++--- jerry-core/mem/mem-heap.h | 13 +++--- jerry-core/mem/mem-poolman.c | 16 ++++---- jerry-core/mem/mem-poolman.h | 28 ++++++------- jerry-core/parser/regexp/re-bytecode.h | 6 +-- jerry-core/parser/regexp/re-parser.h | 40 +++++++++---------- 34 files changed, 177 insertions(+), 214 deletions(-) diff --git a/jerry-core/ecma/base/ecma-alloc.h b/jerry-core/ecma/base/ecma-alloc.h index 865be9464..cf7bc5e1a 100644 --- a/jerry-core/ecma/base/ecma-alloc.h +++ b/jerry-core/ecma/base/ecma-alloc.h @@ -1,4 +1,4 @@ -/* Copyright 2014-2015 Samsung Electronics Co., Ltd. +/* Copyright 2014-2016 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -13,6 +13,11 @@ * limitations under the License. */ +#ifndef ECMA_ALLOC_H +#define ECMA_ALLOC_H + +#include "ecma-globals.h" + /** \addtogroup ecma ECMA * @{ * @@ -20,11 +25,6 @@ * @{ */ -#ifndef ECMA_ALLOC_H -#define ECMA_ALLOC_H - -#include "ecma-globals.h" - /** * Allocate memory for ecma-object * @@ -121,10 +121,9 @@ extern ecma_external_pointer_t *ecma_alloc_external_pointer (void); */ extern void ecma_dealloc_external_pointer (ecma_external_pointer_t *); - -#endif /* !ECMA_ALLOC_H */ - /** * @} * @} */ + +#endif /* !ECMA_ALLOC_H */ diff --git a/jerry-core/ecma/base/ecma-gc.c b/jerry-core/ecma/base/ecma-gc.c index cb1bf15aa..a73a78a4b 100644 --- a/jerry-core/ecma/base/ecma-gc.c +++ b/jerry-core/ecma/base/ecma-gc.c @@ -13,13 +13,6 @@ * limitations under the License. */ -/** \addtogroup ecma ECMA - * @{ - * - * \addtogroup ecmagc Garbage collector - * @{ - */ - /** * Garbage collector implementation */ @@ -41,6 +34,13 @@ /* TODO: Extract GC to a separate component */ +/** \addtogroup ecma ECMA + * @{ + * + * \addtogroup ecmagc Garbage collector + * @{ + */ + /** * An object's GC color * diff --git a/jerry-core/ecma/base/ecma-gc.h b/jerry-core/ecma/base/ecma-gc.h index 6d2e8a668..e33dae9c6 100644 --- a/jerry-core/ecma/base/ecma-gc.h +++ b/jerry-core/ecma/base/ecma-gc.h @@ -1,4 +1,4 @@ -/* Copyright 2014-2015 Samsung Electronics Co., Ltd. +/* Copyright 2014-2016 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -13,6 +13,12 @@ * limitations under the License. */ +#ifndef ECMA_GC_H +#define ECMA_GC_H + +#include "ecma-globals.h" +#include "mem-allocator.h" + /** \addtogroup ecma ECMA * @{ * @@ -20,12 +26,6 @@ * @{ */ -#ifndef ECMA_GC_H -#define ECMA_GC_H - -#include "ecma-globals.h" -#include "mem-allocator.h" - extern void ecma_gc_init (void); extern void ecma_init_gc_info (ecma_object_t *); extern void ecma_ref_object (ecma_object_t *); @@ -33,9 +33,9 @@ extern void ecma_deref_object (ecma_object_t *); extern void ecma_gc_run (void); extern void ecma_try_to_give_back_some_memory (mem_try_give_memory_back_severity_t); -#endif /* !ECMA_GC_H */ - /** * @} * @} */ + +#endif /* !ECMA_GC_H */ diff --git a/jerry-core/ecma/base/ecma-globals.h b/jerry-core/ecma/base/ecma-globals.h index c1c34695f..38ce23752 100644 --- a/jerry-core/ecma/base/ecma-globals.h +++ b/jerry-core/ecma/base/ecma-globals.h @@ -14,13 +14,6 @@ * limitations under the License. */ -/** \addtogroup ecma ECMA - * @{ - * - * \addtogroup ecmatypes ECMA types - * @{ - */ - #ifndef ECMA_GLOBALS_H #define ECMA_GLOBALS_H @@ -29,7 +22,13 @@ #include "lit-magic-strings.h" #include "mem-allocator.h" -/** \addtogroup compressedpointer Compressed pointer +/** \addtogroup ecma ECMA + * @{ + * + * \addtogroup ecmatypes ECMA types + * @{ + * + * \addtogroup compressedpointer Compressed pointer * @{ */ @@ -727,12 +726,8 @@ typedef struct } ecma_compiled_code_t; /** + * @} * @} */ #endif /* !ECMA_GLOBALS_H */ - -/** - * @} - * @} - */ diff --git a/jerry-core/ecma/base/ecma-helpers-conversion.c b/jerry-core/ecma/base/ecma-helpers-conversion.c index 2ee12a037..bc6612e26 100644 --- a/jerry-core/ecma/base/ecma-helpers-conversion.c +++ b/jerry-core/ecma/base/ecma-helpers-conversion.c @@ -14,20 +14,18 @@ * limitations under the License. */ -/** \addtogroup ecma ECMA - * @{ - * - * \addtogroup ecmahelpers Helpers for operations with ECMA data types - * @{ - */ - #include "ecma-globals.h" #include "ecma-helpers.h" #include "jrt-libc-includes.h" #include "lit-char-helpers.h" #include "lit-magic-strings.h" -/* +/** \addtogroup ecma ECMA + * @{ + * + * \addtogroup ecmahelpers Helpers for operations with ECMA data types + * @{ + * * \addtogroup ecmahelpersbigintegers Helpers for operations intermediate 128-bit integers * @{ */ diff --git a/jerry-core/ecma/base/ecma-helpers-external-pointers.c b/jerry-core/ecma/base/ecma-helpers-external-pointers.c index 485c3d945..d3e7deeae 100644 --- a/jerry-core/ecma/base/ecma-helpers-external-pointers.c +++ b/jerry-core/ecma/base/ecma-helpers-external-pointers.c @@ -14,6 +14,10 @@ * limitations under the License. */ +#include "ecma-alloc.h" +#include "ecma-globals.h" +#include "ecma-helpers.h" + /** \addtogroup ecma ECMA * @{ * @@ -21,10 +25,6 @@ * @{ */ -#include "ecma-alloc.h" -#include "ecma-globals.h" -#include "ecma-helpers.h" - /** * Create internal property with specified identifier and store external pointer in the property. * diff --git a/jerry-core/ecma/base/ecma-helpers-number.c b/jerry-core/ecma/base/ecma-helpers-number.c index a2f168611..e47738289 100644 --- a/jerry-core/ecma/base/ecma-helpers-number.c +++ b/jerry-core/ecma/base/ecma-helpers-number.c @@ -14,6 +14,9 @@ * limitations under the License. */ +#include "ecma-globals.h" +#include "ecma-helpers.h" + /** \addtogroup ecma ECMA * @{ * @@ -21,9 +24,6 @@ * @{ */ -#include "ecma-globals.h" -#include "ecma-helpers.h" - #define ECMA_NUMBER_SIGN_POS (ECMA_NUMBER_FRACTION_WIDTH + \ ECMA_NUMBER_BIASED_EXP_WIDTH) diff --git a/jerry-core/ecma/base/ecma-helpers-string.c b/jerry-core/ecma/base/ecma-helpers-string.c index 89e458892..7c1f7a9f2 100644 --- a/jerry-core/ecma/base/ecma-helpers-string.c +++ b/jerry-core/ecma/base/ecma-helpers-string.c @@ -14,13 +14,6 @@ * limitations under the License. */ -/** \addtogroup ecma ECMA - * @{ - * - * \addtogroup ecmahelpers Helpers for operations with ECMA data types - * @{ - */ - #include "ecma-alloc.h" #include "ecma-gc.h" #include "ecma-globals.h" @@ -34,6 +27,13 @@ #include "lit-literal-storage.h" #include "vm.h" +/** \addtogroup ecma ECMA + * @{ + * + * \addtogroup ecmahelpers Helpers for operations with ECMA data types + * @{ + */ + /** * Maximum length of strings' concatenation */ @@ -745,11 +745,11 @@ ecma_string_get_heap_number_size (mem_cpointer_t number_cp) /**< Compressed poin * NULL - otherwise */ const lit_utf8_byte_t * -ecma_string_raw_chars (const ecma_string_t *string_p, /* ecma-string */ - lit_utf8_size_t *size_p, /* [out] size of the ecma string */ - bool *is_ascii_p) /* [out] true, if the string is an ascii - * character sequence (size == length) - * false, otherwise */ +ecma_string_raw_chars (const ecma_string_t *string_p, /**< ecma-string */ + lit_utf8_size_t *size_p, /**< [out] size of the ecma string */ + bool *is_ascii_p) /**< [out] true, if the string is an ascii + * character sequence (size == length) + * false, otherwise */ { ecma_length_t length; lit_utf8_size_t size; diff --git a/jerry-core/ecma/base/ecma-helpers-value.c b/jerry-core/ecma/base/ecma-helpers-value.c index f34ee5efc..4ddd40e5b 100644 --- a/jerry-core/ecma/base/ecma-helpers-value.c +++ b/jerry-core/ecma/base/ecma-helpers-value.c @@ -14,13 +14,6 @@ * limitations under the License. */ -/** \addtogroup ecma ECMA - * @{ - * - * \addtogroup ecmahelpers Helpers for operations with ECMA data types - * @{ - */ - #include "ecma-alloc.h" #include "ecma-gc.h" #include "ecma-globals.h" @@ -32,6 +25,13 @@ JERRY_STATIC_ASSERT (sizeof (ecma_value_t) * JERRY_BITSINBYTE >= ECMA_VALUE_SIZE, bits_in_ecma_value_t_must_be_greater_than_or_equal_to_ECMA_VALUE_SIZE); +/** \addtogroup ecma ECMA + * @{ + * + * \addtogroup ecmahelpers Helpers for operations with ECMA data types + * @{ + */ + /** * Get type field of ecma value * diff --git a/jerry-core/ecma/base/ecma-helpers-values-collection.c b/jerry-core/ecma/base/ecma-helpers-values-collection.c index 62687da28..ef0719411 100644 --- a/jerry-core/ecma/base/ecma-helpers-values-collection.c +++ b/jerry-core/ecma/base/ecma-helpers-values-collection.c @@ -14,6 +14,11 @@ * limitations under the License. */ +#include "ecma-alloc.h" +#include "ecma-globals.h" +#include "ecma-helpers.h" +#include "jrt.h" + /** \addtogroup ecma ECMA * @{ * @@ -21,11 +26,6 @@ * @{ */ -#include "ecma-alloc.h" -#include "ecma-globals.h" -#include "ecma-helpers.h" -#include "jrt.h" - /** * Allocate a collection of ecma values. * diff --git a/jerry-core/ecma/base/ecma-helpers.c b/jerry-core/ecma/base/ecma-helpers.c index 999866d4b..d80f12214 100644 --- a/jerry-core/ecma/base/ecma-helpers.c +++ b/jerry-core/ecma/base/ecma-helpers.c @@ -14,13 +14,6 @@ * limitations under the License. */ -/** \addtogroup ecma ECMA - * @{ - * - * \addtogroup ecmahelpers Helpers for operations with ECMA data types - * @{ - */ - #include "ecma-alloc.h" #include "ecma-gc.h" #include "ecma-globals.h" @@ -30,6 +23,13 @@ #include "byte-code.h" #include "re-compiler.h" +/** \addtogroup ecma ECMA + * @{ + * + * \addtogroup ecmahelpers Helpers for operations with ECMA data types + * @{ + */ + /** * The ecma object types must be lower than the container mask. */ diff --git a/jerry-core/ecma/base/ecma-helpers.h b/jerry-core/ecma/base/ecma-helpers.h index ad9b1282f..b4d4d7442 100644 --- a/jerry-core/ecma/base/ecma-helpers.h +++ b/jerry-core/ecma/base/ecma-helpers.h @@ -14,13 +14,6 @@ * limitations under the License. */ -/** \addtogroup ecma ECMA - * @{ - * - * \addtogroup ecmahelpers Helpers for operations with ECMA data types - * @{ - */ - #ifndef ECMA_HELPERS_H #define ECMA_HELPERS_H @@ -29,6 +22,13 @@ #include "lit-strings.h" #include "mem-allocator.h" +/** \addtogroup ecma ECMA + * @{ + * + * \addtogroup ecmahelpers Helpers for operations with ECMA data types + * @{ + */ + /** * Get value of pointer from specified non-null compressed pointer. */ @@ -276,9 +276,9 @@ extern uint32_t ecma_number_to_uint32 (ecma_number_t); extern int32_t ecma_number_to_int32 (ecma_number_t); extern lit_utf8_size_t ecma_number_to_utf8_string (ecma_number_t, lit_utf8_byte_t *, lit_utf8_size_t); -#endif /* !ECMA_HELPERS_H */ - /** * @} * @} */ + +#endif /* !ECMA_HELPERS_H */ diff --git a/jerry-core/ecma/base/ecma-init-finalize.h b/jerry-core/ecma/base/ecma-init-finalize.h index 68f1efd2b..b7f88df6a 100644 --- a/jerry-core/ecma/base/ecma-init-finalize.h +++ b/jerry-core/ecma/base/ecma-init-finalize.h @@ -18,9 +18,7 @@ /** \addtogroup ecma ECMA * @{ - */ - -/** + * * \addtogroup ecmainitfinalize Initialization and finalization of ECMA components * @{ */ diff --git a/jerry-core/ecma/builtin-objects/ecma-builtin-helpers-json.c b/jerry-core/ecma/builtin-objects/ecma-builtin-helpers-json.c index 37c634044..68ea97578 100644 --- a/jerry-core/ecma/builtin-objects/ecma-builtin-helpers-json.c +++ b/jerry-core/ecma/builtin-objects/ecma-builtin-helpers-json.c @@ -1,4 +1,4 @@ -/* Copyright 2014-2015 Samsung Electronics Co., Ltd. +/* Copyright 2014-2016 Samsung Electronics Co., Ltd. * Copyright 2015-2016 University of Szeged. * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -14,6 +14,11 @@ * limitations under the License. */ +#include "ecma-alloc.h" +#include "ecma-helpers.h" +#include "ecma-builtin-helpers.h" +#include "lit-char-helpers.h" + /** \addtogroup ecma ECMA * @{ * @@ -21,11 +26,6 @@ * @{ */ -#include "ecma-alloc.h" -#include "ecma-helpers.h" -#include "ecma-builtin-helpers.h" -#include "lit-char-helpers.h" - /** * Check the object value existance in the collection. * diff --git a/jerry-core/ecma/builtin-objects/ecma-builtin-helpers.c b/jerry-core/ecma/builtin-objects/ecma-builtin-helpers.c index 56e66e5fa..d5a52ac70 100644 --- a/jerry-core/ecma/builtin-objects/ecma-builtin-helpers.c +++ b/jerry-core/ecma/builtin-objects/ecma-builtin-helpers.c @@ -123,7 +123,7 @@ ecma_builtin_helper_object_to_string (const ecma_value_t this_arg) /**< this arg */ ecma_value_t ecma_builtin_helper_get_to_locale_string_at_index (ecma_object_t *obj_p, /**< this object */ - uint32_t index) /**