Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 13, 2018
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions Doxyfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
77 changes: 53 additions & 24 deletions jerry-core/ecma/base/ecma-globals.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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 */

Expand Down Expand Up @@ -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
Expand All @@ -743,7 +763,7 @@ typedef struct
ecma_value_t bytecode_cp; /**< function byte code */
} function;

/*
/**
* Description of array objects.
*/
struct
Expand All @@ -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 */
Expand All @@ -772,7 +792,7 @@ typedef struct
} u2;
} pseudo_array;

/*
/**
* Description of bound function object.
*/
struct
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)

/**
Expand Down Expand Up @@ -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

/**
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really like these comment duplications. Is there a better way to do this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are no easy ways and/or this is the way that's compatible with the rest of ecma-globals.h. (E.g., see the documentation of ecma_number_t, ECMA_NUMBER_MAX_DIGITS, ECMA_NUMBER_SIGN_WIDTH, ECMA_NUMBER_BIASED_EXP_WIDTH, and ECMA_NUMBER_FRACTION_WIDTH.) I've followed that approach here, too.

FYI, there may be one way to reduce duplication by using @def MACRONAME(args) doxygen syntax to break out documentation from before the macro definitions, but that might necessitate a bigger rewrite throughout the code base (to apply that approach everywhere where macros (or typedefs, or functions) are conditionally defined multiple times). Moreover, that approach should be discussed further as it splits the documentation from the documented entity, making maintenance somewhat harder. So, I'd have that separate from this PR.

(To restate: this PR tries to fix the problem in the Doxyfile with the least friction, fixing only the fallout that can be easily fixed, leaving the rest for follow-up.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can use @copydoc or groups to avoid duplication in comments. Maybe my previous PR can help: #2324

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But you cannot copy documentation when an entity is defined multiple times because of conditional compilation, can you? I guess you cannot copydoc self.

#if COND
/** documentation of X */
#define X
/** documentation of Y */
#define Y
#else
/** @copydoc X */   // <-- THIS SHOULDN'T WORK
#define X
/** @copydoc Y */   // <-- THIS SHOULDN'T WORK
#define Y
#endif

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IHMO the default macro conditions should be documented. The Doxygen docs will be generated with the default config. BTW you can use a group comment before the #if which should work independently from the configuration. Although this can be useful in simple cases only (like your example in the prev. comment).

*/
#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
*/
Expand Down
10 changes: 10 additions & 0 deletions jerry-core/ecma/builtin-objects/ecma-builtins.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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, \
Expand All @@ -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, \
Expand All @@ -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, \
Expand All @@ -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, \
Expand All @@ -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 */
};

/**
Expand Down Expand Up @@ -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, \
Expand All @@ -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. */
Expand Down
2 changes: 2 additions & 0 deletions jerry-core/ecma/builtin-objects/ecma-builtins.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
*/
typedef enum
{
/** @cond doxygen_suppress */
#define BUILTIN(a, b, c, d, e)
#define BUILTIN_ROUTINE(builtin_id, \
object_type, \
Expand All @@ -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;

Expand Down
2 changes: 1 addition & 1 deletion jerry-core/ecma/builtin-objects/typedarray/ecma-builtin-typedarray-helpers.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
/** \addtogroup ecma ECMA
* @{
*
* \addtogroup ecmabuiltinhelpers ECMA TypedArray helper operations
* \addtogroup ecmabuiltinhelpers ECMA builtin helper operations
* @{
*/

Expand Down
Loading