From 90539f48b320e0a197c497d6eecac30b5d00aef6 Mon Sep 17 00:00:00 2001 From: Jittapan Pluemsumran Date: Fri, 23 Sep 2016 21:34:55 +0700 Subject: [PATCH] Added English comments in nullpo.h (#1556) * Added English comments in nullpo.h * Updated comment formatting * Added _f functions for Visual Studio --- src/common/nullpo.h | 234 +++++++++++++++++++++----------------------- 1 file changed, 110 insertions(+), 124 deletions(-) diff --git a/src/common/nullpo.h b/src/common/nullpo.h index 5427665f48..19493a295a 100644 --- a/src/common/nullpo.h +++ b/src/common/nullpo.h @@ -14,212 +14,198 @@ #define NULLPO_CHECK #endif -/*---------------------------------------------------------------------------- - * Macros - *---------------------------------------------------------------------------- - */ -/*====================================== - * Nullチェック 及び 情報出力後 return - *・展開するとifとかreturn等が出るので - * 一行単体で使ってください。 - *・nullpo_ret(x = func()); - * のような使用法も想定しています。 - *-------------------------------------- - * nullpo_ret(t) - * 戻り値 0固定 - * [引数] - * t チェック対象 - *-------------------------------------- - * nullpo_retv(t) - * 戻り値 なし - * [引数] - * t チェック対象 - *-------------------------------------- - * nullpo_retr(ret, t) - * 戻り値 指定 - * [引数] - * ret return(ret); - * t チェック対象 - *-------------------------------------- - * nullpo_ret_f(t, fmt, ...) - * 詳細情報出力用 - * 戻り値 0 - * [引数] - * t チェック対象 - * fmt ... vprintfに渡される - * 備考や関係変数の書き出しなどに - *-------------------------------------- - * nullpo_retv_f(t, fmt, ...) - * 詳細情報出力用 - * 戻り値 なし - * [引数] - * t チェック対象 - * fmt ... vprintfに渡される - * 備考や関係変数の書き出しなどに - *-------------------------------------- - * nullpo_retr_f(ret, t, fmt, ...) - * 詳細情報出力用 - * 戻り値 指定 - * [引数] - * ret return(ret); - * t チェック対象 - * fmt ... vprintfに渡される - * 備考や関係変数の書き出しなどに - *-------------------------------------- - */ - #if defined(NULLPO_CHECK) +/** + * Macros used to check for NULL pointer and output that information. + */ + +/** + * Return 0 if pointer is not found. + * @param t: Pointer to check + * @return 0 if t is NULL + */ #define nullpo_ret(t) \ if (nullpo_chk(NLP_MARK, (void *)(t))) {return(0);} +/** + * Return void if pointer is not found. + * @param t: Pointer to check + * @return void if t is NULL + */ #define nullpo_retv(t) \ if (nullpo_chk(NLP_MARK, (void *)(t))) {return;} +/** + * Return the given value if pointer is not found. + * @param ret: Value to return + * @param t: Pointer to check + * @return ret value + */ #define nullpo_retr(ret, t) \ if (nullpo_chk(NLP_MARK, (void *)(t))) {return(ret);} +/** + * Break out of the loop/switch if pointer is not found. + * @param t: Pointer to check + */ #define nullpo_retb(t) \ if (nullpo_chk(NLP_MARK, (void *)(t))) {break;} -// 可変引数マクロに関する条件コンパイル -#if __STDC_VERSION__ >= 199901L -/* C99に対応 */ +// Different C compilers uses different argument formats +#if __STDC_VERSION__ >= 199901L || defined(_MSC_VER) +/* C99 standard */ +/** + * Return 0 and display additional information if pointer is not found. + * @param t: Pointer to check + * @param fmt: Pass to vprintf, Format and arguments such as description + * @return 0 if t is NULL + */ #define nullpo_ret_f(t, fmt, ...) \ if (nullpo_chk_f(NLP_MARK, (void *)(t), (fmt), __VA_ARGS__)) {return(0);} +/** + * Return void and display additional information if pointer is not found. + * @param t: Pointer to check + * @param fmt: Pass to vprintf, Format and arguments such as description + * @return void if t is NULL + */ #define nullpo_retv_f(t, fmt, ...) \ if (nullpo_chk_f(NLP_MARK, (void *)(t), (fmt), __VA_ARGS__)) {return;} +/** + * Return the given value and display additional information if pointer is not found. + * @param t: Pointer to check + * @param fmt: Pass to vprintf, Format and arguments such as description + * @return ret value + */ #define nullpo_retr_f(ret, t, fmt, ...) \ if (nullpo_chk_f(NLP_MARK, (void *)(t), (fmt), __VA_ARGS__)) {return(ret);} +/** + * Break out of the loop/switch and display additional information if pointer is not found. + * @param t: Pointer to check + * @param fmt: Pass to vprintf, Format and arguments such as description + */ #define nullpo_retb_f(t, fmt, ...) \ if (nullpo_chk_f(NLP_MARK, (void *)(t), (fmt), __VA_ARGS__)) {break;} #elif __GNUC__ >= 2 -/* GCC用 */ +/* For GCC */ +/** + * Return 0 and display additional information if pointer is not found. + * @param t: Pointer to check + * @param fmt: Pass to vprintf, Format and arguments such as description + * @return 0 if t is NULL + */ #define nullpo_ret_f(t, fmt, args...) \ if (nullpo_chk_f(NLP_MARK, (void *)(t), (fmt), ## args)) {return(0);} +/** + * Return void and display additional information if pointer is not found. + * @param t: Pointer to check + * @param fmt: Pass to vprintf, Format and arguments such as description + * @return void if t is NULL + */ #define nullpo_retv_f(t, fmt, args...) \ if (nullpo_chk_f(NLP_MARK, (void *)(t), (fmt), ## args)) {return;} +/** + * Return the given value and display additional information if pointer is not found. + * @param t: Pointer to check + * @param fmt: Pass to vprintf, Format and arguments such as description + * @return ret value + */ #define nullpo_retr_f(ret, t, fmt, args...) \ if (nullpo_chk_f(NLP_MARK, (void *)(t), (fmt), ## args)) {return(ret);} +/** + * Break out of the loop/switch and display additional information if pointer is not found. + * @param t: Pointer to check + * @param fmt: Pass to vprintf, Format and arguments such as description + */ #define nullpo_retb_f(t, fmt, args...) \ if (nullpo_chk_f(NLP_MARK, (void *)(t), (fmt), ## args)) {break;} #else - -/* その他の場合・・・ orz */ - +/* Otherwise... */ #endif #else /* NULLPO_CHECK */ + /* No Nullpo check */ // if((t)){;} -// 良い方法が思いつかなかったので・・・苦肉の策です。 -// 一応ワーニングは出ないはず +// Do nothing if Nullpo check is disabled #define nullpo_ret(t) (void)(t) #define nullpo_retv(t) (void)(t) #define nullpo_retr(ret, t) (void)(t) #define nullpo_retb(t) (void)(t) -// 可変引数マクロに関する条件コンパイル -#if __STDC_VERSION__ >= 199901L -/* C99に対応 */ +// Different C compilers uses different argument formats +#if __STDC_VERSION__ >= 199901L || defined(_MSC_VER) +/* C99 standard */ #define nullpo_ret_f(t, fmt, ...) (void)(t) #define nullpo_retv_f(t, fmt, ...) (void)(t) #define nullpo_retr_f(ret, t, fmt, ...) (void)(t) #define nullpo_retb_f(t, fmt, ...) (void)(t) #elif __GNUC__ >= 2 -/* GCC用 */ +/* For GCC */ #define nullpo_ret_f(t, fmt, args...) (void)(t) #define nullpo_retv_f(t, fmt, args...) (void)(t) #define nullpo_retr_f(ret, t, fmt, args...) (void)(t) #define nullpo_retb_f(t, fmt, args...) (void)(t) #else -/* その他の場合・・・ orz */ +/* Otherwise... orz */ #endif #endif /* NULLPO_CHECK */ -/*---------------------------------------------------------------------------- - * Functions - *---------------------------------------------------------------------------- - */ -/*====================================== - * nullpo_chk - * Nullチェック 及び 情報出力 - * [引数] - * file __FILE__ - * line __LINE__ - * func __func__ (関数名) - * これらには NLP_MARK を使うとよい - * target チェック対象 - * [返り値] - * 0 OK - * 1 NULL - *-------------------------------------- +/** + * Check for NULL pointer and output information. + * @param file: __FILE__ + * @param line: __LINE__ + * @param func: __func__ (name of the function) [NLP_MARK] + * @param target: Target to check + * @return 0 on success or 1 on NULL */ int nullpo_chk(const char *file, int line, const char *func, const void *target); - -/*====================================== - * nullpo_chk_f - * Nullチェック 及び 詳細な情報出力 - * [引数] - * file __FILE__ - * line __LINE__ - * func __func__ (関数名) - * これらには NLP_MARK を使うとよい - * target チェック対象 - * fmt ... vprintfに渡される - * 備考や関係変数の書き出しなどに - * [返り値] - * 0 OK - * 1 NULL - *-------------------------------------- +/** + * Check for NULL pointer and output detailed information. + * @param file: __FILE__ + * @param line: __LINE__ + * @param func: __func__ (name of the function) [NLP_MARK] + * @param target: Target to check + * @param fmt: Passed to vprintf + * @return 0 on success or 1 on NULL */ int nullpo_chk_f(const char *file, int line, const char *func, const void *target, const char *fmt, ...) __attribute__((format(printf,5,6))); - -/*====================================== - * nullpo_info - * nullpo情報出力 - * [引数] - * file __FILE__ - * line __LINE__ - * func __func__ (関数名) - * これらには NLP_MARK を使うとよい - *-------------------------------------- +/** + * Display information of the code that cause this function to trigger. + * @param file: __FILE__ + * @param line: __LINE__ + * @param func: __func__ (name of the function) [NLP_MARK] + * @param target: Target to check */ void nullpo_info(const char *file, int line, const char *func); - -/*====================================== - * nullpo_info_f - * nullpo詳細情報出力 - * [引数] - * file __FILE__ - * line __LINE__ - * func __func__ (関数名) - * これらには NLP_MARK を使うとよい - * fmt ... vprintfに渡される - * 備考や関係変数の書き出しなどに - *-------------------------------------- +/** + * Check for NULL pointer and output detailed information. + * @param file: __FILE__ + * @param line: __LINE__ + * @param func: __func__ (name of the function) [NLP_MARK] + * @param target: Target to check + * @param fmt: Passed to vprintf */ void nullpo_info_f(const char *file, int line, const char *func, const char *fmt, ...) __attribute__((format(printf,4,5))); - #endif /* _NULLPO_H_ */