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
This commit is contained in:
Akos Kiss 2016-04-09 21:27:43 +02:00
parent a7f015ef47
commit 9aca0086b9
34 changed files with 177 additions and 214 deletions

View File

@ -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 */

View File

@ -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
*

View File

@ -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 */

View File

@ -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 */
/**
* @}
* @}
*/

View File

@ -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
* @{
*/

View File

@ -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.
*

View File

@ -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)

View File

@ -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;

View File

@ -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
*

View File

@ -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.
*

View File

@ -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.
*/

View File

@ -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 */

View File

@ -18,9 +18,7 @@
/** \addtogroup ecma ECMA
* @{
*/
/**
*
* \addtogroup ecmainitfinalize Initialization and finalization of ECMA components
* @{
*/

View File

@ -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.
*

View File

@ -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) /** <array index */
uint32_t index) /**< array index */
{
ecma_value_t ret_value = ecma_make_simple_value (ECMA_SIMPLE_VALUE_EMPTY);
ecma_string_t *index_string_p = ecma_new_ecma_string_from_uint32 (index);

View File

@ -28,6 +28,7 @@
* @{
*
* \addtogroup eval eval
* @{
*/
/**

View File

@ -22,6 +22,7 @@
* @{
*
* \addtogroup eval eval
* @{
*/
extern ecma_value_t

View File

@ -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.
@ -23,9 +23,7 @@
/** \addtogroup ecma ECMA
* @{
*/
/**
*
* \addtogroup exceptions Exceptions
* @{
*/

View File

@ -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.
@ -21,9 +21,7 @@
/** \addtogroup ecma ECMA
* @{
*/
/**
*
* \addtogroup exceptions Exceptions
* @{
*/

View File

@ -26,14 +26,10 @@
/** \addtogroup ecma ECMA
* @{
*/
/**
*
* \addtogroup lexicalenvironment Lexical environment
* @{
*/
/**
*
* \addtogroup globallexicalenvironment Global lexical environment
* @{
*/

View File

@ -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.
@ -22,14 +22,10 @@
/** \addtogroup ecma ECMA
* @{
*/
/**
*
* \addtogroup lexicalenvironment Lexical environment
* @{
*/
/**
*
* \addtogroup globallexicalenvironment Global lexical environment
* @{
*/

View File

@ -19,9 +19,7 @@
/** \addtogroup ecma ECMA
* @{
*/
/**
*
* \addtogroup numberarithmetic ECMA number arithmetic operations
* @{
*/

View File

@ -20,9 +20,7 @@
/** \addtogroup ecma ECMA
* @{
*/
/**
*
* \addtogroup numberarithmetic ECMA number arithmetic operations
* @{
*/

View File

@ -14,13 +14,6 @@
* limitations under the License.
*/
/** \addtogroup ecma ECMA
* @{
*
* \addtogroup ecmafunctionobject ECMA Function object related routines
* @{
*/
#include "ecma-alloc.h"
#include "ecma-builtin-helpers.h"
#include "ecma-builtins.h"
@ -35,6 +28,13 @@
#include "ecma-try-catch-macro.h"
#include "jrt.h"
/** \addtogroup ecma ECMA
* @{
*
* \addtogroup ecmafunctionobject ECMA Function object related routines
* @{
*/
/**
* Arguments object creation operation.
*

View File

@ -23,9 +23,7 @@
/** \addtogroup ecma ECMA
* @{
*/
/**
*
* \addtogroup references ECMA-Reference
* @{
*/

View File

@ -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.
@ -21,9 +21,7 @@
/** \addtogroup ecma ECMA
* @{
*/
/**
*
* \addtogroup references ECMA-Reference
* @{
*/

View File

@ -25,7 +25,6 @@
#include "mem-poolman.h"
#define MEM_ALLOCATOR_INTERNAL
#include "mem-allocator-internal.h"
/**

View File

@ -13,10 +13,6 @@
* limitations under the License.
*/
/** \addtogroup mem Memory allocation
* @{
*/
/**
* Allocator interface
*/
@ -28,6 +24,10 @@
#include "mem-heap.h"
#include "mem-poolman.h"
/** \addtogroup mem Memory allocation
* @{
*/
/**
* Compressed pointer
*/
@ -125,8 +125,8 @@ extern void mem_stats_reset_peak (void);
extern void mem_stats_print (void);
#endif /* MEM_STATS */
#endif /* !MEM_ALLOCATOR_H */
/**
* @}
*/
#endif /* !MEM_ALLOCATOR_H */

View File

@ -14,13 +14,6 @@
* limitations under the License.
*/
/** \addtogroup mem Memory allocation
* @{
*
* \addtogroup heap Heap
* @{
*/
/**
* Heap implementation
*/
@ -33,9 +26,15 @@
#include "mem-heap.h"
#define MEM_ALLOCATOR_INTERNAL
#include "mem-allocator-internal.h"
/** \addtogroup mem Memory allocation
* @{
*
* \addtogroup heap Heap
* @{
*/
/*
* Valgrind-related options and headers
*/

View File

@ -14,13 +14,6 @@
* limitations under the License.
*/
/** \addtogroup mem Memory allocation
* @{
*
* \addtogroup heap Heap
* @{
*/
/**
* Heap allocator interface
*/
@ -29,6 +22,12 @@
#include "jrt.h"
/** \addtogroup mem Memory allocation
* @{
*
* \addtogroup heap Heap
* @{
*/
extern void mem_heap_init (void);
extern void mem_heap_finalize (void);

View File

@ -14,13 +14,6 @@
* limitations under the License.
*/
/** \addtogroup mem Memory allocation
* @{
*
* \addtogroup poolman Memory pool manager
* @{
*/
/**
* Memory pool manager implementation
*/
@ -34,6 +27,13 @@
#define MEM_ALLOCATOR_INTERNAL
#include "mem-allocator-internal.h"
/** \addtogroup mem Memory allocation
* @{
*
* \addtogroup poolman Memory pool manager
* @{
*/
/**
* Node for free chunk list
*/
@ -308,7 +308,5 @@ mem_pools_stat_dealloc (void)
/**
* @}
*/
/**
* @}
*/

View File

@ -14,14 +14,6 @@
* limitations under the License.
*/
/** \addtogroup mem Memory allocation
* @{
*/
/** \addtogroup poolman Memory pool manager
* @{
*/
/**
* Pool manager interface
*/
@ -30,6 +22,13 @@
#include "jrt.h"
/** \addtogroup mem Memory allocation
* @{
*
* \addtogroup poolman Memory pool manager
* @{
*/
extern void mem_pools_init (void);
extern void mem_pools_finalize (void);
extern void *mem_pools_alloc (void);
@ -66,12 +65,9 @@ extern void mem_pools_stats_reset_peak (void);
extern void mem_pools_stats_print (void);
#endif /* MEM_STATS */
/**
* @}
* @}
*/
#endif /* !MEM_POOLMAN_H */
/**
* @}
*/
/**
* @}
*/

View File

@ -75,9 +75,9 @@ typedef enum
RE_OP_ASSERT_NOT_WORD_BOUNDARY, /**< "\B" */
RE_OP_LOOKAHEAD_POS, /**< lookahead pos */
RE_OP_LOOKAHEAD_NEG, /**< lookahead neg */
RE_OP_BACKREFERENCE, /**< \[0..9] */
RE_OP_CHAR_CLASS, /**< [ ] */
RE_OP_INV_CHAR_CLASS /**< [^ ] */
RE_OP_BACKREFERENCE, /**< "\[0..9]" */
RE_OP_CHAR_CLASS, /**< "[ ]" */
RE_OP_INV_CHAR_CLASS /**< "[^ ]" */
} re_opcode_t;
/**

View File

@ -35,27 +35,27 @@
typedef enum
{
RE_TOK_EOF, /**< EOF */
RE_TOK_BACKREFERENCE, /**< \[0..9] */
RE_TOK_BACKREFERENCE, /**< "\[0..9]" */
RE_TOK_CHAR, /**< any character */
RE_TOK_ALTERNATIVE, /**< | */
RE_TOK_ASSERT_START, /**< ^ */
RE_TOK_ASSERT_END, /**< $ */
RE_TOK_PERIOD, /**< . */
RE_TOK_START_CAPTURE_GROUP, /**< ( */
RE_TOK_START_NON_CAPTURE_GROUP, /**< (?: */
RE_TOK_END_GROUP, /**< ')' */
RE_TOK_ASSERT_START_POS_LOOKAHEAD, /**< (?= */
RE_TOK_ASSERT_START_NEG_LOOKAHEAD, /**< (?! */
RE_TOK_ASSERT_WORD_BOUNDARY, /**< \b */
RE_TOK_ASSERT_NOT_WORD_BOUNDARY, /**< \B */
RE_TOK_DIGIT, /**< \d */
RE_TOK_NOT_DIGIT, /**< \D */
RE_TOK_WHITE, /**< \s */
RE_TOK_NOT_WHITE, /**< \S */
RE_TOK_WORD_CHAR, /**< \w */
RE_TOK_NOT_WORD_CHAR, /**< \W */
RE_TOK_START_CHAR_CLASS, /**< [ ] */
RE_TOK_START_INV_CHAR_CLASS, /**< [^ ] */
RE_TOK_ALTERNATIVE, /**< "|" */
RE_TOK_ASSERT_START, /**< "^" */
RE_TOK_ASSERT_END, /**< "$" */
RE_TOK_PERIOD, /**< "." */
RE_TOK_START_CAPTURE_GROUP, /**< "(" */
RE_TOK_START_NON_CAPTURE_GROUP, /**< "(?:" */
RE_TOK_END_GROUP, /**< ")" */
RE_TOK_ASSERT_START_POS_LOOKAHEAD, /**< "(?=" */
RE_TOK_ASSERT_START_NEG_LOOKAHEAD, /**< "(?!" */
RE_TOK_ASSERT_WORD_BOUNDARY, /**< "\b" */
RE_TOK_ASSERT_NOT_WORD_BOUNDARY, /**< "\B" */
RE_TOK_DIGIT, /**< "\d" */
RE_TOK_NOT_DIGIT, /**< "\D" */
RE_TOK_WHITE, /**< "\s" */
RE_TOK_NOT_WHITE, /**< "\S" */
RE_TOK_WORD_CHAR, /**< "\w" */
RE_TOK_NOT_WORD_CHAR, /**< "\W" */
RE_TOK_START_CHAR_CLASS, /**< "[ ]" */
RE_TOK_START_INV_CHAR_CLASS, /**< "[^ ]" */
} re_token_type_t;
/**