Fix FILE_PATTERNS of Doxyfile and some of the issues it was hiding (#2446)

`FILE_PATTERNS` is a space-separated list, in contrary to what is
suggested by its documentation. The pattern `*.h, *.c` does not
match header files but files with `.h,` extension only. Rewriting
the current comma-separated pattern makes Doxygen actually process
header files. However, it also reveals several hitherto hidden
issues (mostly missing documentation) in the code. This patch fixes
some of these documentation problems (and lists the files with
outstanding issues in a 'backlog').

JerryScript-DCO-1.0-Signed-off-by: Akos Kiss akiss@inf.u-szeged.hu

12 files changed, 181 insertions, 57 deletions

diff --git a/Doxyfile b/Doxyfile
index ac603a9d..725b3e33 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -778,7 +778,7 @@ INPUT_ENCODING         = UTF-8
 # *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
 # *.qsf, *.as and *.js.
 
-FILE_PATTERNS          = *.h, *.c
+FILE_PATTERNS          = *.h *.c
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -793,7 +793,21 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+# FIXME: None of these files are excluded light-heartedly. They should be
+# removed one-by-one and warnings reported by doxygen should be fixed by those
+# who are familiar with the undocumented parts.
+EXCLUDE                = \
+        jerry-core/ecma/base/ecma-globals.h \
+        jerry-core/ecma/base/ecma-helpers.h \
+        jerry-core/ecma/operations/ecma-exceptions.h \
+        jerry-core/include/jerryscript-debugger-transport.h \
+        jerry-core/jcontext/jcontext.h \
+        jerry-core/parser/js/byte-code.h \
+        jerry-core/parser/js/common.h \
+        jerry-core/parser/js/js-lexer.h \
+        jerry-core/parser/js/js-parser-internal.h \
+        jerry-core/parser/regexp/re-parser.h \
+        jerry-core/vm/vm-stack.h
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -809,7 +823,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = *.inc.h
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -2000,7 +2014,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = JERRY_STATIC_ASSERT(x,y)=
+PREDEFINED             = JERRY_STATIC_ASSERT(x,y)= JERRY_ATTR_FORMAT(x,y,z)=
 
 # 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/ecma/base/ecma-globals.h b/jerry-core/ecma/base/ecma-globals.h
index b97822b9..344893b8 100644
--- a/jerry-core/ecma/base/ecma-globals.h
+++ b/jerry-core/ecma/base/ecma-globals.h
@@ -142,7 +142,9 @@ typedef int32_t ecma_integer_value_t;
  */
 #define ECMA_DIRECT_SHIFT 4
 
-/* ECMA make simple value */
+/**
+ * ECMA make simple value
+ */
 #define ECMA_MAKE_VALUE(value) \
   ((((ecma_value_t) (value)) << ECMA_DIRECT_SHIFT) | ECMA_DIRECT_TYPE_SIMPLE_VALUE)
 
@@ -171,25 +173,43 @@ enum
                                                                 *   a special "base" value for vm */
 };
 
+#if CONFIG_ECMA_NUMBER_TYPE == CONFIG_ECMA_NUMBER_FLOAT32
 /**
  * Maximum integer number for an ecma value
  */
-#if CONFIG_ECMA_NUMBER_TYPE == CONFIG_ECMA_NUMBER_FLOAT32
 #define ECMA_INTEGER_NUMBER_MAX         0x7fffff
+/**
+ * Maximum integer number for an ecma value (shifted left with ECMA_DIRECT_SHIFT)
+ */
 #define ECMA_INTEGER_NUMBER_MAX_SHIFTED 0x7fffff0
 #else /* CONFIG_ECMA_NUMBER_TYPE != CONFIG_ECMA_NUMBER_FLOAT32 */
+/**
+ * Maximum integer number for an ecma value
+ */
 #define ECMA_INTEGER_NUMBER_MAX         0x7ffffff
+/**
+ * Maximum integer number for an ecma value (shifted left with ECMA_DIRECT_SHIFT)
+ */
 #define ECMA_INTEGER_NUMBER_MAX_SHIFTED 0x7ffffff0
 #endif /* CONFIG_ECMA_NUMBER_TYPE == CONFIG_ECMA_NUMBER_FLOAT32 */
 
+#if CONFIG_ECMA_NUMBER_TYPE == CONFIG_ECMA_NUMBER_FLOAT32
 /**
  * Minimum integer number for an ecma value
  */
-#if CONFIG_ECMA_NUMBER_TYPE == CONFIG_ECMA_NUMBER_FLOAT32
 #define ECMA_INTEGER_NUMBER_MIN         -0x7fffff
+/**
+ * Minimum integer number for an ecma value (shifted left with ECMA_DIRECT_SHIFT)
+ */
 #define ECMA_INTEGER_NUMBER_MIN_SHIFTED -0x7fffff0
 #else /* CONFIG_ECMA_NUMBER_TYPE != CONFIG_ECMA_NUMBER_FLOAT32 */
+/**
+ * Minimum integer number for an ecma value
+ */
 #define ECMA_INTEGER_NUMBER_MIN         -0x8000000
+/**
+ * Minimum integer number for an ecma value (shifted left with ECMA_DIRECT_SHIFT)
+ */
 #define ECMA_INTEGER_NUMBER_MIN_SHIFTED (-0x7fffffff - 1) /* -0x80000000 */
 #endif /* CONFIG_ECMA_NUMBER_TYPE == CONFIG_ECMA_NUMBER_FLOAT32 */
 
@@ -708,33 +728,33 @@ typedef struct
 {
   ecma_object_t object; /**< object header */
 
-  /*
-   * Description of extra fields. These extra fields depends on the object type.
+  /**
+   * Description of extra fields. These extra fields depend on the object type.
    */
   union
   {
     ecma_built_in_props_t built_in; /**< built-in object part */
 
-    /*
+    /**
      * Description of objects with class.
      */
     struct
     {
       uint16_t class_id; /**< class id of the object */
       uint16_t extra_info; /**< extra information for the object
-                                e.g. array buffer type info (external/internal) */
+                            *   e.g. array buffer type info (external/internal) */
 
-      /*
-       * Description of extra fields. These extra fields depends on the class_id.
+      /**
+       * Description of extra fields. These extra fields depend on the class_id.
        */
       union
       {
         ecma_value_t value; /**< value of the object (e.g. boolean, number, string, etc.) */
-        uint32_t length; /**< length related property  (e.g. length of ArrayBuffer) */
+        uint32_t length; /**< length related property (e.g. length of ArrayBuffer) */
       } u;
     } class_prop;
 
-    /*
+    /**
      * Description of function objects.
      */
     struct
@@ -743,7 +763,7 @@ typedef struct
       ecma_value_t bytecode_cp; /**< function byte code */
     } function;
 
-    /*
+    /**
      * Description of array objects.
      */
     struct
@@ -752,14 +772,14 @@ typedef struct
       ecma_property_t length_prop; /**< length property */
     } array;
 
-    /*
+    /**
      * Description of pseudo array objects.
      */
     struct
     {
       uint8_t type; /**< pseudo array type, e.g. Arguments, TypedArray*/
-      uint8_t extra_info; /**< extra infomations about the object.
-                            *  e.g. element_width_shift for typed arrays */
+      uint8_t extra_info; /**< extra information about the object.
+                           *   e.g. element_width_shift for typed arrays */
       union
       {
         uint16_t length; /**< for arguments: length of names */
@@ -772,7 +792,7 @@ typedef struct
       } u2;
     } pseudo_array;
 
-    /*
+    /**
      * Description of bound function object.
      */
     struct
@@ -802,10 +822,10 @@ typedef struct
   uint16_t size;                    /**< real size >> JMEM_ALIGNMENT_LOG */
   uint16_t refs;                    /**< reference counter for the byte code */
   uint16_t status_flags;            /**< various status flags:
-                                      *    CBC_CODE_FLAGS_FUNCTION flag tells whether
-                                      *    the byte code is function or regular expression.
-                                      *    If function, the other flags must be CBC_CODE_FLAGS...
-                                      *    If regexp, the other flags must be RE_FLAG... */
+                                     *   CBC_CODE_FLAGS_FUNCTION flag tells whether
+                                     *   the byte code is function or regular expression.
+                                     *   If function, the other flags must be CBC_CODE_FLAGS...
+                                     *   If regexp, the other flags must be RE_FLAG... */
 } ecma_compiled_code_t;
 
 #ifdef JERRY_ENABLE_SNAPSHOT_EXEC
@@ -902,6 +922,7 @@ typedef struct
  * Description of an ecma-number
  */
 typedef float ecma_number_t;
+
 #define DOUBLE_TO_ECMA_NUMBER_T(value) (ecma_number_t) (value)
 
 /**
@@ -937,6 +958,7 @@ typedef float ecma_number_t;
  * Description of an ecma-number
  */
 typedef double ecma_number_t;
+
 #define DOUBLE_TO_ECMA_NUMBER_T(value) value
 
 /**
@@ -994,21 +1016,28 @@ typedef double ecma_number_t;
  */
 #define ECMA_NUMBER_MINUS_ONE ((ecma_number_t) -1)
 
+#if CONFIG_ECMA_NUMBER_TYPE == CONFIG_ECMA_NUMBER_FLOAT32
 /**
- * Minimum positive and maximum value of ecma-number
+ * Number.MIN_VALUE (i.e., the smallest positive value of ecma-number)
+ *
+ * See also: ECMA_262 v5, 15.7.3.3
  */
-#if CONFIG_ECMA_NUMBER_TYPE == CONFIG_ECMA_NUMBER_FLOAT32
 # define ECMA_NUMBER_MIN_VALUE (FLT_MIN)
+/**
+ * Number.MAX_VALUE (i.e., the maximum value of ecma-number)
+ *
+ * See also: ECMA_262 v5, 15.7.3.2
+ */
 # define ECMA_NUMBER_MAX_VALUE (FLT_MAX)
 #elif CONFIG_ECMA_NUMBER_TYPE == CONFIG_ECMA_NUMBER_FLOAT64
 /**
- * Number.MAX_VALUE
+ * Number.MAX_VALUE (i.e., the maximum value of ecma-number)
  *
  * See also: ECMA_262 v5, 15.7.3.2
  */
 # define ECMA_NUMBER_MAX_VALUE ((ecma_number_t) 1.7976931348623157e+308)
 /**
- * Number.MIN_VALUE
+ * Number.MIN_VALUE (i.e., the smallest positive value of ecma-number)
  *
  * See also: ECMA_262 v5, 15.7.3.3
  */
diff --git a/jerry-core/ecma/builtin-objects/ecma-builtins.c b/jerry-core/ecma/builtin-objects/ecma-builtins.c
index a79a9f98..0154aa5b 100644
--- a/jerry-core/ecma/builtin-objects/ecma-builtins.c
+++ b/jerry-core/ecma/builtin-objects/ecma-builtins.c
@@ -56,6 +56,7 @@ typedef ecma_value_t (*ecma_builtin_dispatch_call_t)(const ecma_value_t argument
  */
 static const ecma_builtin_dispatch_routine_t ecma_builtin_routines[] =
 {
+/** @cond doxygen_suppress */
 #define BUILTIN(a, b, c, d, e)
 #define BUILTIN_ROUTINE(builtin_id, \
                         object_type, \
@@ -76,6 +77,7 @@ static const ecma_builtin_dispatch_routine_t ecma_builtin_routines[] =
 #include "ecma-builtins.inc.h"
 #undef BUILTIN
 #undef BUILTIN_ROUTINE
+/** @endcond */
 };
 
 /**
@@ -83,6 +85,7 @@ static const ecma_builtin_dispatch_routine_t ecma_builtin_routines[] =
  */
 static const ecma_builtin_dispatch_call_t ecma_builtin_call_functions[] =
 {
+/** @cond doxygen_suppress */
 #define BUILTIN(a, b, c, d, e)
 #define BUILTIN_ROUTINE(builtin_id, \
                         object_type, \
@@ -93,6 +96,7 @@ static const ecma_builtin_dispatch_call_t ecma_builtin_call_functions[] =
 #include "ecma-builtins.inc.h"
 #undef BUILTIN_ROUTINE
 #undef BUILTIN
+/** @endcond */
 };
 
 /**
@@ -100,6 +104,7 @@ static const ecma_builtin_dispatch_call_t ecma_builtin_call_functions[] =
  */
 static const ecma_builtin_dispatch_call_t ecma_builtin_construct_functions[] =
 {
+/** @cond doxygen_suppress */
 #define BUILTIN(a, b, c, d, e)
 #define BUILTIN_ROUTINE(builtin_id, \
                         object_type, \
@@ -110,6 +115,7 @@ static const ecma_builtin_dispatch_call_t ecma_builtin_construct_functions[] =
 #include "ecma-builtins.inc.h"
 #undef BUILTIN_ROUTINE
 #undef BUILTIN
+/** @endcond */
 };
 
 /**
@@ -117,6 +123,7 @@ static const ecma_builtin_dispatch_call_t ecma_builtin_construct_functions[] =
  */
 static const ecma_builtin_property_list_reference_t ecma_builtin_property_list_references[] =
 {
+/** @cond doxygen_suppress */
 #define BUILTIN(a, b, c, d, e)
 #define BUILTIN_ROUTINE(builtin_id, \
                         object_type, \
@@ -137,6 +144,7 @@ static const ecma_builtin_property_list_reference_t ecma_builtin_property_list_r
 #include "ecma-builtins.inc.h"
 #undef BUILTIN_ROUTINE
 #undef BUILTIN
+/** @endcond */
 };
 
 /**
@@ -435,6 +443,7 @@ ecma_instantiate_builtin (ecma_builtin_id_t id) /**< built-in id */
   JERRY_ASSERT (id < ECMA_BUILTIN_ID__COUNT);
   switch (id)
   {
+/** @cond doxygen_suppress */
 #define BUILTIN(builtin_id, \
                 object_type, \
                 object_prototype_builtin_id, \
@@ -452,6 +461,7 @@ ecma_instantiate_builtin (ecma_builtin_id_t id) /**< built-in id */
 #include "ecma-builtins.inc.h"
 #undef BUILTIN
 #undef BUILTIN_ROUTINE
+/** @endcond */
     default:
     {
       JERRY_UNREACHABLE (); /* The built-in is not implemented. */
diff --git a/jerry-core/ecma/builtin-objects/ecma-builtins.h b/jerry-core/ecma/builtin-objects/ecma-builtins.h
index 593843b8..8b2fbaec 100644
--- a/jerry-core/ecma/builtin-objects/ecma-builtins.h
+++ b/jerry-core/ecma/builtin-objects/ecma-builtins.h
@@ -23,6 +23,7 @@
  */
 typedef enum
 {
+/** @cond doxygen_suppress */
 #define BUILTIN(a, b, c, d, e)
 #define BUILTIN_ROUTINE(builtin_id, \
                         object_type, \
@@ -43,6 +44,7 @@ typedef enum
 #include "ecma-builtins.inc.h"
 #undef BUILTIN
 #undef BUILTIN_ROUTINE
+/** @endcond */
   ECMA_BUILTIN_ID__COUNT /**< number of built-in objects */
 } ecma_builtin_id_t;
 
diff --git a/jerry-core/ecma/builtin-objects/typedarray/ecma-builtin-typedarray-helpers.h b/jerry-core/ecma/builtin-objects/typedarray/ecma-builtin-typedarray-helpers.h
index db98ddbf..764208d3 100644
--- a/jerry-core/ecma/builtin-objects/typedarray/ecma-builtin-typedarray-helpers.h
+++ b/jerry-core/ecma/builtin-objects/typedarray/ecma-builtin-typedarray-helpers.h
@@ -22,7 +22,7 @@
 /** \addtogroup ecma ECMA
  * @{
  *
- * \addtogroup ecmabuiltinhelpers ECMA TypedArray helper operations
+ * \addtogroup ecmabuiltinhelpers ECMA builtin helper operations
  * @{
  */
 
diff --git a/jerry-core/include/jerryscript-compiler.h b/jerry-core/include/jerryscript-compiler.h
index 6ac30b81..726d9861 100644
--- a/jerry-core/include/jerryscript-compiler.h
+++ b/jerry-core/include/jerryscript-compiler.h
@@ -70,64 +70,105 @@ void * __cdecl _alloca (size_t _Size);
  * these in a guarded block above (e.g., as for GCC) to fine tune compilation
  * for your own compiler. */
 
-/*
- * Attributes
+/**
+ * Function attribute to align function to given number of bytes.
  */
 #ifndef JERRY_ATTR_ALIGNED
 #define JERRY_ATTR_ALIGNED(ALIGNMENT)
 #endif /* !JERRY_ATTR_ALIGNED */
 
+/**
+ * Function attribute to inline function to all call sites.
+ */
 #ifndef JERRY_ATTR_ALWAYS_INLINE
 #define JERRY_ATTR_ALWAYS_INLINE
 #endif /* !JERRY_ATTR_ALWAYS_INLINE */
 
+/**
+ * Function attribute to declare that function has no effect except the return
+ * value and it only depends on parameters.
+ */
 #ifndef JERRY_ATTR_CONST
 #define JERRY_ATTR_CONST
 #endif /* !JERRY_ATTR_CONST */
 
+/**
+ * Function attribute to trigger warning if deprecated function is called.
+ */
 #ifndef JERRY_ATTR_DEPRECATED
 #define JERRY_ATTR_DEPRECATED
 #endif /* !JERRY_ATTR_DEPRECATED */
 
+/**
+ * Function attribute to declare that function is variadic and takes a format
+ * string and some arguments as parameters.
+ */
 #ifndef JERRY_ATTR_FORMAT
 #define JERRY_ATTR_FORMAT(...)
 #endif /* !JERRY_ATTR_FORMAT */
 
+/**
+ * Function attribute to predict that function is a hot spot, and therefore
+ * should be optimized aggressively.
+ */
 #ifndef JERRY_ATTR_HOT
 #define JERRY_ATTR_HOT
 #endif /* !JERRY_ATTR_HOT */
 
+/**
+ * Function attribute not to inline function ever.
+ */
 #ifndef JERRY_ATTR_NOINLINE
 #define JERRY_ATTR_NOINLINE
 #endif /* !JERRY_ATTR_NOINLINE */
 
+/**
+ * Function attribute to declare that function never returns.
+ */
 #ifndef JERRY_ATTR_NORETURN
 #define JERRY_ATTR_NORETURN
 #endif /* !JERRY_ATTR_NORETURN */
 
+/**
+ * Function attribute to declare that function has no effect except the return
+ * value and it only depends on parameters and global variables.
+ */
 #ifndef JERRY_ATTR_PURE
 #define JERRY_ATTR_PURE
 #endif /* !JERRY_ATTR_PURE */
 
+/**
+ * Function attribute to place function in given section.
+ */
 #ifndef JERRY_ATTR_SECTION
 #define JERRY_ATTR_SECTION(SECTION)
 #endif /* !JERRY_ATTR_SECTION */
 
+/**
+ * Function attribute to trigger warning if function's caller doesn't use (e.g.,
+ * check) the return value.
+ */
 #ifndef JERRY_ATTR_WARN_UNUSED_RESULT
 #define JERRY_ATTR_WARN_UNUSED_RESULT
 #endif /* !JERRY_ATTR_WARN_UNUSED_RESULT */
 
-/*
- * Condition likeliness, unlikeliness
+/**
+ * Helper to predict that a condition is likely.
  */
 #ifndef JERRY_LIKELY
 #define JERRY_LIKELY(x) (x)
 #endif /* !JERRY_LIKELY */
 
+/**
+ * Helper to predict that a condition is unlikely.
+ */
 #ifndef JERRY_UNLIKELY
 #define JERRY_UNLIKELY(x) (x)
 #endif /* !JERRY_UNLIKELY */
 
+/**
+ * Helper to declare (or mimic) a C99 variable-length array.
+ */
 #ifndef JERRY_VLA
 #define JERRY_VLA(type, name, size) type name[size]
 #endif /* !JERRY_VLA */
diff --git a/jerry-core/lit/lit-magic-strings.c b/jerry-core/lit/lit-magic-strings.c
index 08cd5a41..183e400c 100644
--- a/jerry-core/lit/lit-magic-strings.c
+++ b/jerry-core/lit/lit-magic-strings.c
@@ -39,12 +39,14 @@ lit_get_magic_string_utf8 (lit_magic_string_id_t id) /**< magic string id */
 {
   static const lit_utf8_byte_t * const lit_magic_strings[] JERRY_CONST_DATA =
   {
+/** @cond doxygen_suppress */
 #define LIT_MAGIC_STRING_FIRST_STRING_WITH_SIZE(size, id)
 #define LIT_MAGIC_STRING_DEF(id, utf8_string) \
     (const lit_utf8_byte_t *) utf8_string,
 #include "lit-magic-strings.inc.h"
 #undef LIT_MAGIC_STRING_DEF
 #undef LIT_MAGIC_STRING_FIRST_STRING_WITH_SIZE
+/** @endcond */
   };
 
   JERRY_ASSERT (id < LIT_NON_INTERNAL_MAGIC_STRING__COUNT);
@@ -62,12 +64,14 @@ lit_get_magic_string_size (lit_magic_string_id_t id) /**< magic string id */
 {
   static const lit_magic_size_t lit_magic_string_sizes[] JERRY_CONST_DATA =
   {
+/** @cond doxygen_suppress */
 #define LIT_MAGIC_STRING_FIRST_STRING_WITH_SIZE(size, id)
 #define LIT_MAGIC_STRING_DEF(id, utf8_string) \
     sizeof(utf8_string) - 1,
 #include "lit-magic-strings.inc.h"
 #undef LIT_MAGIC_STRING_DEF
 #undef LIT_MAGIC_STRING_FIRST_STRING_WITH_SIZE
+/** @endcond */
   };
 
   JERRY_ASSERT (id < LIT_NON_INTERNAL_MAGIC_STRING__COUNT);
@@ -86,6 +90,7 @@ lit_get_magic_string_size_block_start (lit_utf8_size_t size) /**< magic string s
 {
   static const lit_magic_string_id_t lit_magic_string_size_block_starts[] JERRY_CONST_DATA =
   {
+/** @cond doxygen_suppress */
 #define LIT_MAGIC_STRING_DEF(id, utf8_string)
 #define LIT_MAGIC_STRING_FIRST_STRING_WITH_SIZE(size, id) \
     id,
@@ -93,6 +98,7 @@ lit_get_magic_string_size_block_start (lit_utf8_size_t size) /**< magic string s
     LIT_NON_INTERNAL_MAGIC_STRING__COUNT
 #undef LIT_MAGIC_STRING_DEF
 #undef LIT_MAGIC_STRING_FIRST_STRING_WITH_SIZE
+/** @endcond */
   };
 
   JERRY_ASSERT (size <= (sizeof (lit_magic_string_size_block_starts) / sizeof (lit_magic_string_id_t)));
diff --git a/jerry-core/lit/lit-magic-strings.h b/jerry-core/lit/lit-magic-strings.h
index 8f31b974..8d470e8d 100644
--- a/jerry-core/lit/lit-magic-strings.h
+++ b/jerry-core/lit/lit-magic-strings.h
@@ -23,12 +23,14 @@
  */
 typedef enum
 {
+/** @cond doxygen_suppress */
 #define LIT_MAGIC_STRING_FIRST_STRING_WITH_SIZE(size, id)
 #define LIT_MAGIC_STRING_DEF(id, ascii_zt_string) \
      id,
 #include "lit-magic-strings.inc.h"
 #undef LIT_MAGIC_STRING_DEF
 #undef LIT_MAGIC_STRING_FIRST_STRING_WITH_SIZE
+/** @endcond */
   LIT_NON_INTERNAL_MAGIC_STRING__COUNT, /**< number of non-internal magic strings */
   LIT_INTERNAL_MAGIC_STRING_PROMISE = LIT_NON_INTERNAL_MAGIC_STRING__COUNT, /**<  [[Promise]] of promise
                                                                              *    reject or resolve functions */
diff --git a/jerry-core/parser/js/common.h b/jerry-core/parser/js/common.h
index 1e88a94f..a0e8eec2 100644
--- a/jerry-core/parser/js/common.h
+++ b/jerry-core/parser/js/common.h
@@ -57,21 +57,21 @@ typedef enum
 
 /* Flags for status_flags. */
 
-/* Local identifier (var, function arg). */
+/** Local identifier (var, function arg). */
 #define LEXER_FLAG_VAR 0x01
-/* This local identifier cannot be stored in register. */
+/** This local identifier cannot be stored in register. */
 #define LEXER_FLAG_NO_REG_STORE 0x02
-/* This local identifier is initialized with a value. */
+/** This local identifier is initialized with a value. */
 #define LEXER_FLAG_INITIALIZED 0x04
-/* This local identifier has a reference to the function itself. */
+/** This local identifier has a reference to the function itself. */
 #define LEXER_FLAG_FUNCTION_NAME 0x08
-/* This local identifier is a function argument. */
+/** This local identifier is a function argument. */
 #define LEXER_FLAG_FUNCTION_ARGUMENT 0x10
-/* This local identifier is not used in the current context. */
+/** This local identifier is not used in the current context. */
 #define LEXER_FLAG_UNUSED_IDENT 0x20
-/* No space is allocated for this character literal. */
+/** No space is allocated for this character literal. */
 #define LEXER_FLAG_SOURCE_PTR 0x40
-/* Initialize this variable after the byte code is freed. */
+/** Initialize this variable after the byte code is freed. */
 #define LEXER_FLAG_LATE_INIT 0x80
 
 /**
diff --git a/jerry-core/parser/js/js-parser-limits.h b/jerry-core/parser/js/js-parser-limits.h
index 01774261..e7b334c1 100644
--- a/jerry-core/parser/js/js-parser-limits.h
+++ b/jerry-core/parser/js/js-parser-limits.h
@@ -26,46 +26,60 @@
  * @{
  */
 
-/* Maximum identifier length accepted by the parser.
- * Limit: LEXER_MAX_STRING_LENGTH. */
+/**
+ * Maximum identifier length accepted by the parser.
+ * Limit: LEXER_MAX_STRING_LENGTH.
+ */
 #ifndef PARSER_MAXIMUM_IDENT_LENGTH
 #define PARSER_MAXIMUM_IDENT_LENGTH 255
 #endif /* !PARSER_MAXIMUM_IDENT_LENGTH */
 
-/* Maximum string limit.
- * Limit: 2147483647 / 65535. */
+/**
+ * Maximum string limit.
+ * Limit: 2147483647 / 65535.
+ */
 #ifdef JERRY_CPOINTER_32_BIT
 #define PARSER_MAXIMUM_STRING_LIMIT 2147483647
 #else /* !JERRY_CPOINTER_32_BIT */
 #define PARSER_MAXIMUM_STRING_LIMIT 65535
 #endif /* JERRY_CPOINTER_32_BIT */
 
-/* Maximum string length.
- * Limit: PARSER_MAXIMUM_STRING_LIMIT. */
+/**
+ * Maximum string length.
+ * Limit: PARSER_MAXIMUM_STRING_LIMIT.
+ */
 #ifndef PARSER_MAXIMUM_STRING_LENGTH
 #define PARSER_MAXIMUM_STRING_LENGTH PARSER_MAXIMUM_STRING_LIMIT
 #endif /* !PARSER_MAXIMUM_STRING_LENGTH */
 
-/* Maximum number of literals.
- * Limit: 32767. Recommended: 510, 32767 */
+/**
+ * Maximum number of literals.
+ * Limit: 32767. Recommended: 510, 32767
+ */
 #ifndef PARSER_MAXIMUM_NUMBER_OF_LITERALS
 #define PARSER_MAXIMUM_NUMBER_OF_LITERALS 32767
 #endif /* !PARSER_MAXIMUM_NUMBER_OF_LITERALS */
 
-/* Maximum number of registers.
- * Limit: PARSER_MAXIMUM_NUMBER_OF_LITERALS */
+/**
+ * Maximum number of registers.
+ * Limit: PARSER_MAXIMUM_NUMBER_OF_LITERALS
+ */
 #ifndef PARSER_MAXIMUM_NUMBER_OF_REGISTERS
 #define PARSER_MAXIMUM_NUMBER_OF_REGISTERS 256
 #endif /* !PARSER_MAXIMUM_NUMBER_OF_REGISTERS */
 
-/* Maximum code size.
- * Limit: 16777215. Recommended: 65535, 16777215. */
+/**
+ * Maximum code size.
+ * Limit: 16777215. Recommended: 65535, 16777215.
+ */
 #ifndef PARSER_MAXIMUM_CODE_SIZE
 #define PARSER_MAXIMUM_CODE_SIZE (65535 << (JMEM_ALIGNMENT_LOG))
 #endif /* !PARSER_MAXIMUM_CODE_SIZE */
 
-/* Maximum number of values pushed onto the stack by a function.
- * Limit: 65500. Recommended: 1024. */
+/**
+ * Maximum number of values pushed onto the stack by a function.
+ * Limit: 65500. Recommended: 1024.
+ */
 #ifndef PARSER_MAXIMUM_STACK_LIMIT
 #define PARSER_MAXIMUM_STACK_LIMIT 1024
 
diff --git a/jerry-core/parser/js/js-parser.h b/jerry-core/parser/js/js-parser.h
index 0f48cc48..bc1bd56e 100644
--- a/jerry-core/parser/js/js-parser.h
+++ b/jerry-core/parser/js/js-parser.h
@@ -122,7 +122,9 @@ typedef enum
   PARSER_ERR_NON_STRICT_ARG_DEFINITION                /**< non-strict argument definition */
 } parser_error_t;
 
-/* Source code line counter type. */
+/**
+ * Source code line counter type.
+ */
 typedef uint32_t parser_line_counter_t;
 
 /**
diff --git a/jerry-core/vm/vm-defines.h b/jerry-core/vm/vm-defines.h
index 9ad4c3a5..06e81528 100644
--- a/jerry-core/vm/vm-defines.h
+++ b/jerry-core/vm/vm-defines.h
@@ -26,9 +26,13 @@
  */
 
 /**
- * Helpers for updating uint16_t values.
+ * Helper for += on uint16_t values.
  */
 #define VM_PLUS_EQUAL_U16(base, value) (base) = (uint16_t) ((base) + (value))
+
+/**
+ * Helper for -= on uint16_t values.
+ */
 #define VM_MINUS_EQUAL_U16(base, value) (base) = (uint16_t) ((base) - (value))
 
 /**