From 80dfcd497cf436b04755d5b276de18535a713694 Mon Sep 17 00:00:00 2001 From: hyung-hwan Date: Tue, 17 Feb 2009 21:27:03 +0000 Subject: [PATCH] documented the source code a little bit --- qse/README | 2 +- qse/doc/robodoc.rc | 9 ++++++- qse/include/qse/awk/awk.h | 57 ++++++++++++++++++++------------------- qse/include/qse/types.h | 40 ++++++++++++++------------- qse/lib/awk/Awk.cpp | 7 ++--- qse/lib/utl/Makefile.in | 2 +- qse/test/awk/awk01.c | 8 ++++++ qse/test/awk/awk03.c | 15 +++++++---- 8 files changed, 83 insertions(+), 57 deletions(-) diff --git a/qse/README b/qse/README index bfeb7178..a1e3a9ca 100644 --- a/qse/README +++ b/qse/README @@ -12,4 +12,4 @@ Cross compiling for WIN32 with MINGW32 Generate the API documents with robodoc. - robodoc --rc doc/robodoc.rc --css doc/robodoc.css --src include/qse --src test --doc ./doc/qse --multidoc --index --html --source_line_numbers --nopre + robodoc --rc doc/robodoc.rc --css doc/robodoc.css --src . --doc ./doc/qse --multidoc --index --html diff --git a/qse/doc/robodoc.rc b/qse/doc/robodoc.rc index 23150212..22d94479 100644 --- a/qse/doc/robodoc.rc +++ b/qse/doc/robodoc.rc @@ -11,6 +11,7 @@ items: RETURNS EXAMPLE EXAMPLES + NOTE NOTES BUGS SEE ALSO @@ -28,6 +29,7 @@ item order: RETURNS EXAMPLE EXAMPLES + NOTE NOTES BUGS SEE ALSO @@ -40,9 +42,14 @@ ignore files: .svn headertypes: o "Overview" robo_overview 10 - S "Sample Code" robo_sample 11 + d "Definitions" robo_definitions 6 + t "Types" robo_types 5 + s "Structures" robo_structures 5 + f "Functions" robo_functions 4 + S "Samples" robo_samples 0 options: --cmode --nopre --documenttitle "QSE" --source_line_numbers + --tabsize 4 diff --git a/qse/include/qse/awk/awk.h b/qse/include/qse/awk/awk.h index c8df6e15..241b81b0 100644 --- a/qse/include/qse/awk/awk.h +++ b/qse/include/qse/awk/awk.h @@ -24,7 +24,7 @@ #include #include -/****o* AWK/AWK Interpreter +/****o* AWK/Interpreter * DESCRIPTION * The library includes an AWK interpreter that can be embedded into other * applications or can run stand-alone. @@ -1074,7 +1074,7 @@ qse_char_t* qse_awk_strdup ( qse_char_t* qse_awk_strxdup ( qse_awk_t* awk, const qse_char_t* str, - qse_size_t len + qse_size_t len ); /******/ @@ -1134,12 +1134,13 @@ void qse_awk_rtx_close ( * RETURN * The qse_awk_rtx_loop() function returns 0 on success and -1 on failure. * EXAMPLE - * rtx = qse_awk_rtx_open (awk, rio, rcb, QSE_NULL, QSE_NULL); - * if (rtx != QSE_NULL) - * { - * qse_awk_rtx_loop (rtx); - * qse_awk_rtx_close (rtx); - * } + * The example shows typical usage of the function. + * rtx = qse_awk_rtx_open (awk, rio, rcb, QSE_NULL, QSE_NULL); + * if (rtx != QSE_NULL) + * { + * qse_awk_rtx_loop (rtx); + * qse_awk_rtx_close (rtx); + * } * SYNOPSIS */ int qse_awk_rtx_loop ( @@ -1158,13 +1159,14 @@ int qse_awk_rtx_loop ( * RETURN * The qse_awk_rtx_call() function returns 0 on success and -1 on failure. * EXAMPLE - * rtx = qse_awk_rtx_open (awk, rio, rcb, QSE_NULL, QSE_NULL); - * if (rtx != QSE_NULL) - * { - * qse_awk_rtx_call (rtx, QSE_T("init"), QSE_NULL, 0); - * qse_awk_rtx_call (rtx, QSE_T("fini"), QSE_NULL, 0); - * qse_awk_rtx_close (rtx); - * } + * The example shows typical usage of the function. + * rtx = qse_awk_rtx_open (awk, rio, rcb, QSE_NULL, QSE_NULL); + * if (rtx != QSE_NULL) + * { + * qse_awk_rtx_call (rtx, QSE_T("init"), QSE_NULL, 0); + * qse_awk_rtx_call (rtx, QSE_T("fini"), QSE_NULL, 0); + * qse_awk_rtx_close (rtx); + * } * SYNOPSIS */ int qse_awk_rtx_call ( @@ -1308,7 +1310,7 @@ void qse_awk_rtx_setretval ( */ int qse_awk_rtx_setfilename ( qse_awk_rtx_t* rtx, - const qse_char_t* name, + const qse_char_t* str, qse_size_t len ); /******/ @@ -1320,7 +1322,7 @@ int qse_awk_rtx_setfilename ( */ int qse_awk_rtx_setofilename ( qse_awk_rtx_t* rtx, - const qse_char_t* name, + const qse_char_t* str, qse_size_t len ); /******/ @@ -1525,17 +1527,16 @@ qse_char_t* qse_awk_rtx_valtostr ( * RETURN * The qse_awk_rtx_valtonum() function returns -1 on error, 0 if the converted * number is a long number and 1 if it is a real number. - * EXAMPLES - * The following example show how to convert a value to a number and - * determine if it is an integer or a floating-point number. - * qse_long_t l; - * qse_real_t r; - * int n; - * - * n = qse_awk_rtx_valtonum (v, &l, &r); - * if (n == -1) error (); - * else if (n == 0) do_long (l); - * else if (n == 1) do_real (r); + * EXAMPLE + * The example show how to convert a value to a number and determine + * if it is an integer or a floating-point number. + * qse_long_t l; + * qse_real_t r; + * int n; + * n = qse_awk_rtx_valtonum (v, &l, &r); + * if (n == -1) error (); + * else if (n == 0) print_long (l); + * else if (n == 1) print_real (r); * SYNOPSIS */ int qse_awk_rtx_valtonum ( diff --git a/qse/include/qse/types.h b/qse/include/qse/types.h index c9dfbfe7..d6f840a2 100644 --- a/qse/include/qse/types.h +++ b/qse/include/qse/types.h @@ -77,8 +77,8 @@ typedef enum qse_tri_t qse_tri_t; /****t* Base/qse_int_t,Base/qse_uint_t * NAME - * qse_int_t - define a signed integer type as large as a pointer type - * qse_uint_t - define an unsigned integer type as large as a pointer type + * * qse_int_t - define a signed integer type as large as a pointer type + * * qse_uint_t - define an unsigned integer type as large as a pointer type ****** */ #if (defined(hpux) || defined(__hpux) || defined(__hpux__)) && \ @@ -109,8 +109,8 @@ typedef enum qse_tri_t qse_tri_t; /****t* Base/qse_long_t,Base/qse_ulong_t * NAME - * qse_long_t - define the largest signed integer type supported - * qse_ulong_t - define the largest unsigned integer type supported + * * qse_long_t - define the largest signed integer type supported + * * qse_ulong_t - define the largest unsigned integer type supported ****** */ #if QSE_SIZEOF_LONG_LONG > 0 @@ -126,8 +126,8 @@ typedef enum qse_tri_t qse_tri_t; /****t* Base/qse_int8_t,Base/qse_uint8_t * NAME - * qse_int8_t - define an 8-bit signed integer type - * qse_uint8_t - define an 8-bit unsigned integer type + * * qse_int8_t - define an 8-bit signed integer type + * * qse_uint8_t - define an 8-bit unsigned integer type ****** */ #if QSE_SIZEOF_CHAR == 1 @@ -140,8 +140,8 @@ typedef enum qse_tri_t qse_tri_t; /****t* Base/qse_int16_t,Base/qse_uint16_t * NAME - * qse_int16_t - define a 16-bit signed integer type - * qse_uint16_t - define a 16-bit unsigned integer type + * * qse_int16_t - define a 16-bit signed integer type + * * qse_uint16_t - define a 16-bit unsigned integer type ****** */ #if QSE_SIZEOF_SHORT == 2 @@ -154,8 +154,8 @@ typedef enum qse_tri_t qse_tri_t; /****t* Base/qse_int32_t,Base/qse_uint32_t * NAME - * qse_int32_t - define a 32-bit signed integer type - * qse_uint32_t - define a 32-bit unsigned integer type + * * qse_int32_t - define a 32-bit signed integer type + * * qse_uint32_t - define a 32-bit unsigned integer type ****** */ #if QSE_SIZEOF_INT == 4 @@ -171,8 +171,8 @@ typedef enum qse_tri_t qse_tri_t; /****t* Base/qse_int64_t,Base/qse_uint64_t * NAME - * qse_int64_t - define a 64-bit signed integer type - * qse_uint64_t - define a 64-bit unsigned integer type + * * qse_int64_t - define a 64-bit signed integer type + * * qse_uint64_t - define a 64-bit unsigned integer type ****** */ #if QSE_SIZEOF_INT == 8 @@ -267,8 +267,8 @@ typedef qse_uint_t qse_word_t; /****t* Base/qse_mchar_t,Base/qse_mcint_t * NAME - * qse_mchar_t - define a multi-byte character - * qse_mcint_t - define a type that can hold qse_mchar_t and QSE_MCHAR_EOF + * * qse_mchar_t - define a multi-byte character + * * qse_mcint_t - define a type that can hold qse_mchar_t and QSE_MCHAR_EOF ****** */ typedef char qse_mchar_t; @@ -276,8 +276,8 @@ typedef int qse_mcint_t; /****t* Base/qse_wchar_t,Base/qse_wcint_t * NAME - * qse_wchar_t - define a wide character - * qse_wcint_t - define a type that can hold qse_wchar_t and QSE_WCHAR_EOF + * * qse_wchar_t - define a wide character + * * qse_wcint_t - define a type that can hold qse_wchar_t and QSE_WCHAR_EOF ****** */ #if defined(__cplusplus) && \ @@ -335,8 +335,8 @@ typedef int qse_mcint_t; /****t* Base/qse_char_t,Base/qse_cint_t * NAME - * qse_char_t - define a character - * qse_cint_t - define a type that can hold qse_char_t and QSE_CHAR_EOF + * * qse_char_t - define a character + * * qse_cint_t - define a type that can hold qse_char_t and QSE_CHAR_EOF ****** */ #if defined(_WIN32) && (defined(UNICODE)||defined(_UNICODE)) @@ -378,6 +378,8 @@ typedef struct qse_ccls_t qse_ccls_t; /****t* Base/qse_xstr_t * NAME * qse_xstr_t - combine a pointer and length + * SEE ALSO + * qse_cstr_t * SYNOPSIS */ struct qse_xstr_t @@ -390,6 +392,8 @@ struct qse_xstr_t /****t* Base/qse_cstr_t * NAME * qse_cstr_t - combine a constant pointer and length + * SEE ALSO + * qse_xstr_t * SYNOPSIS */ struct qse_cstr_t diff --git a/qse/lib/awk/Awk.cpp b/qse/lib/awk/Awk.cpp index 9ed8f502..f51d4b06 100644 --- a/qse/lib/awk/Awk.cpp +++ b/qse/lib/awk/Awk.cpp @@ -1130,7 +1130,8 @@ void Awk::setError (ErrorCode code, size_t line, const char_t* arg, size_t len) this->errnum = code; this->errlin = line; - const char_t* es = qse_awk_geterrstr (QSE_NULL, code); + const char_t* es = qse_awk_geterrstr ( + QSE_NULL, (qse_awk_errnum_t)code); qse_strxcpy (this->errmsg, QSE_COUNTOF(this->errmsg), es); } } @@ -1281,13 +1282,13 @@ Awk::size_t Awk::getMaxDepth (int id) const const Awk::char_t* Awk::getErrorString (ErrorCode num) const { QSE_ASSERT (awk != QSE_NULL); - return qse_awk_geterrstr (awk, (int)num); + return qse_awk_geterrstr (awk, (qse_awk_errnum_t)num); } int Awk::setErrorString (ErrorCode num, const char_t* str) { QSE_ASSERT (awk != QSE_NULL); - return qse_awk_seterrstr (awk, (int)num, str); + return qse_awk_seterrstr (awk, (qse_awk_errnum_t)num, str); } int Awk::getWord ( diff --git a/qse/lib/utl/Makefile.in b/qse/lib/utl/Makefile.in index 8ded4fef..e1d222fd 100644 --- a/qse/lib/utl/Makefile.in +++ b/qse/lib/utl/Makefile.in @@ -33,7 +33,7 @@ POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ subdir = lib/utl -DIST_COMMON = README $(srcdir)/Makefile.am $(srcdir)/Makefile.in +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/configure.ac am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ diff --git a/qse/test/awk/awk01.c b/qse/test/awk/awk01.c index 535b32c8..c4469179 100644 --- a/qse/test/awk/awk01.c +++ b/qse/test/awk/awk01.c @@ -1,3 +1,9 @@ +/****S* AWK/Basic Loop + * DESCRIPTION + * This program demonstrates how to use qse_awk_rtx_loop(). + * SOURCE + */ + #include #include @@ -61,3 +67,5 @@ oops: if (awk != QSE_NULL) qse_awk_close (awk); return -1; } + +/******/ diff --git a/qse/test/awk/awk03.c b/qse/test/awk/awk03.c index eb920697..d0d9788f 100644 --- a/qse/test/awk/awk03.c +++ b/qse/test/awk/awk03.c @@ -1,4 +1,4 @@ -/****S* Sample/AWK +/****S* AWK/Calling Functions * DESCRIPTION * This program demonstrates how to use qse_awk_rtx_call(). * SOURCE @@ -7,13 +7,13 @@ #include #include -const qse_char_t* src = QSE_T( +static const qse_char_t* src = QSE_T( "function init() { a = 20; }" "function main() { a++; }" "function fini() { print a; }" ); -const qse_char_t* f[] = +static const qse_char_t* f[] = { QSE_T("init"), QSE_T("main"), @@ -29,6 +29,7 @@ int main () qse_awk_rtx_t* rtx = QSE_NULL; int ret, i; + /* create a main processor */ awk = qse_awk_opensimple (); if (awk == QSE_NULL) { @@ -51,6 +52,7 @@ int main () goto oops; } + /* create a runtime context */ rtx = qse_awk_rtx_opensimple ( awk, QSE_NULL /* no console files */ @@ -62,19 +64,22 @@ int main () ret = -1; goto oops; } + /* invoke functions as indicated in the array f */ for (i = 0; i < QSE_COUNTOF(f); i++) { ret = qse_awk_rtx_call (rtx, f[i], QSE_NULL, 0); if (ret == -1) { - qse_fprintf (QSE_STDERR, QSE_T("%d error: %s\n"), - i, qse_awk_rtx_geterrmsg(rtx)); + qse_fprintf (QSE_STDERR, QSE_T("error: %s\n"), + qse_awk_rtx_geterrmsg(rtx)); goto oops; } } oops: + /* destroy a runtime context */ if (rtx != QSE_NULL) qse_awk_rtx_close (rtx); + /* destroy the processor */ if (awk != QSE_NULL) qse_awk_close (awk); return ret; }