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 [email protected]

Author: akosthekiss

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

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

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,13 +77,15 @@ static const ecma_builtin_dispatch_routine_t ecma_builtin_routines[] =
 #include "ecma-builtins.inc.h"
 #undef BUILTIN
 #undef BUILTIN_ROUTINE
+/** @endcond */
 };
 
 /**
  * List of the built-in call functions.
  */
 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,13 +96,15 @@ static const ecma_builtin_dispatch_call_t ecma_builtin_call_functions[] =
 #include "ecma-builtins.inc.h"
 #undef BUILTIN_ROUTINE
 #undef BUILTIN
+/** @endcond */
 };
 
 /**
  * List of the built-in construct 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,13 +115,15 @@ static const ecma_builtin_dispatch_call_t ecma_builtin_construct_functions[] =
 #include "ecma-builtins.inc.h"
 #undef BUILTIN_ROUTINE
 #undef BUILTIN
+/** @endcond */
 };
 
 /**
  * Property descriptor lists for all built-ins.
  */
 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. */

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;
 

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