Merge remote branch 'mob/benny2' into devel
authorChristian Thaeter <ct@pipapo.org>
Sun, 15 Aug 2010 09:01:09 +0000 (11:01 +0200)
committerChristian Thaeter <ct@pipapo.org>
Sun, 15 Aug 2010 09:01:09 +0000 (11:01 +0200)
* mob/benny2:
  Text moved to nobug.h.
  Description of Source Code Annotations expanded.
  Improvements to text describing macros.
  Language and text improvements. No significant change to content.

doc/annotationtable.txt
doc/buildinstall.txt
doc/dumpexample.txt
doc/dumping.txt
src/nobug.h

index ce4edf1..6dd7c2b 100644 (file)
@@ -1,8 +1,4 @@
 
-The advantage of this tagging over plain source comments is that we can take
-some actions if we run in such a tag at compile or runtime:
-
-the action to be taken when such a macro is hit depends on the build level:
 
 [grid="all"]
 `-------------`-----`------------`-----------------------------------------
@@ -18,9 +14,9 @@ NOTREACHED    abort abort        removed
 
 Legend:
 
-  * abort means first log and then abort
-  * log will only log once for each sourceline (not on each hit)
-  * wont compile will abort compilation with a error message
+  * abort means first log, then abort
+  * log will only log once for each source line (not on each hit)
+  * will not compile, will abort compilation with a error message
   * nothing optimized out, sane way
-  * removed optimized out for performance reasons
+  * removed and optimized out for performance reasons
 
index 184355b..a2afdfe 100644 (file)
@@ -111,14 +111,18 @@ Currently, NoBug installs the following:
 
 HEAD== Generating This Documentation;;
 
-There are Makefile targets for generating the documentation, Either one of the
-following does what you may expect:
+There are Makefile targets for generating the documentation, either one of the
+following does what you might expect:
 
  $ make nobug_manual.txt nobug_manual.html nobug_manual.pdf
 
-building the documentation has quite some more dependencies than building
-NoBug itself. Unless you are a packager you may want to refer to the online
-documentation or the shipped 'README' which is this complete nobug reference
+Alternatively, you can generate all the documentation in one go as follows:
+
+  $ make doc
+
+Building the documentation has quite some more dependencies than building
+NoBug itself. Unless you are a packager you may prefer to refer to the online
+documentation or the shipped 'README' which is the complete nobug reference
 manual in text form. Generating the documentation requires: gawk, asciidoc,
-graphviz and some toolchains to further process docbook and latex.
+graphviz and some tool chains to further process docbook and latex.
 
index 66a473e..a01076c 100644 (file)
@@ -10,7 +10,7 @@ struct STRUCTNAME
 }
 -------------------------------------------------------
 
-then you define a function like:
+Thereafter, define a funcion as follows:
 
 [source,c]
 -------------------------------------------------------
@@ -21,7 +21,7 @@ nobug_STRUCTNAME_dump (const struct STRUCTNAME* self,
                        void* extra)
 {
   // check for self != NULL and that the depth
-  // limit did not exceed in recursive datastructures
+  // limit was not exceeded in recursive data structures
   if (self && depth)
   {
     // you may or may not do something with the extra parameter here
@@ -39,7 +39,7 @@ nobug_STRUCTNAME_dump (const struct STRUCTNAME* self,
 }
 -------------------------------------------------------
 
-now you can use the DUMP() macros within the code
+Now you can use the DUMP() macros within the code
 
 [source,c]
 -------------------------------------------------------
index ff56589..13341a7 100644 (file)
@@ -1,12 +1,12 @@
-HEAD- Dumping Datastructures;dumping;
+HEAD- Dumping Data Structures;dumping;
 
 TODO How to write DUMP handlers
 
-One can write functions for dumping complex datastructures using the NoBug
+One can write functions to dump complex data structures using the NoBug
 facilities. This is done by writing a custom function for each
-datastructure to be dumped which may recursively call other dumping
-functions. There are macros for logging within such a dumper function
-and for initiating a dump of a given datastructure.
+data structure to be dumped, which may recursively call other dumping
+functions. There are macros that can log within such a dumper function
+and to initialise a dump of a given data structure.
 
 A dump function has the prototype:
 
@@ -20,8 +20,8 @@ nobug_NAME_dump (const struct NAME* POINTER,
 -------------------------------------------------------
 
 where NAME is the identifier for what you want to dump, POINTER is a pointer
-to the data to be dumped, DEPTH is a integer which will be decremented when
-recursing into the datastructure dumper (your dump function does that, see
+to the data to be dumped, DEPTH is an integer which will be decremented when
+recursing into the data structure dumper (your dump function does that, see
 below) to limit the recursion depth, CONTEXT is a source context generated by
 nobug when you call DUMP() and EXTRA is a pointer transparently passed around
-you can use to store some extra state.
+that you can use to store some additional state.
index 9dc3fa9..bb266dc 100644 (file)
 /*
 //assertions HEAD- Assertions;;
 //assertions
-//assertions PARA CHECK; CHECK; unnconditional assertion for testsuites
+//assertions The assertion set of macros provide a convenient status check
+//assertions on whether to continue running, or gracefully exit execution
+//assertions as some condition was not fulfilled.
+//assertions 
+//assertions PARA CHECK; CHECK; unnconditional assertion for test suites
 //assertions  CHECK(expr, ...)
 //assertions  CHECK_IF(when, expr, ...)
 //assertions
-//assertions This assertion is never optimized out. Its main purpose is for implementing
-//assertions testsuites where one want to assert tests independent of the build level
+//assertions This assertion is never optimized out. Its main purpose is in implementing
+//assertions test suites where one would like to assert tests independent of the build level.
 //assertions
 */
 #define NOBUG_CHECK(expr, ...) \
 //assertions  NOBUG_REQUIRE_CTX(expr, context,...)
 //assertions  NOBUG_REQUIRE_IF_CTX(when, expr, context, ...)
 //assertions
-//assertions Precondition (input) check. Use these macros to validate input a
-//assertions function receives. The checks are enabled in *ALPHA* and *BETA* builds and
-//assertions optimized out in *RELEASE* builds.
+//assertions Precondition (input) check. Use these macros to validate the input a
+//assertions function receives. The checks are enabled in *ALPHA* and *BETA* builds,
+//assertions but are not available in *RELEASE* builds.
 //assertions
 */
 #define NOBUG_REQUIRE(expr, ...) \
 //assertions
 //assertions The `ENSURE_IF` variants are enabled in *ALPHA* and *BETA* builds.
 //assertions
-//assertions In *RELEASE* builds this checks are
-//assertions always optimized out, scopes tagged as `UNCHECKED` are not permitted.
+//assertions In *RELEASE* builds these checks are
+//assertions never available. Scopes tagged as `UNCHECKED` are not permitted.
 //assertions
 */
 #define NOBUG_ENSURE(expr, ...) \
 //assertions  NOBUG_ASSERT_IF_CTX(when, expr, context, ...)
 //assertions
 //assertions Generic check. Use these macros when you want to validate something
-//assertions which doesn't fall into one of the above categories. A example is when
-//assertions a library function can return a unexpected result (scanf with syntax
-//assertions error in the formatstring, when a constant/literal formatstring is
+//assertions which doesn't fall into one of the above categories. An example is when
+//assertions a library function can return an unexpected result (scanf with syntax
+//assertions error in the format string, when a constant/literal format string is
 //assertions expected). The checks are enabled in *ALPHA* and *BETA* builds and
 //assertions optimized out in *RELEASE* builds.
 //assertions
 //dumpmacros  DUMP(flag, type, pointer, depth, extra)
 //dumpmacros  DUMP_IF(when, flag, type, pointer, depth, extra)
 //dumpmacros
-//dumpmacros This macros call a datastructure dump of the object (`pointer`) in question.
+//dumpmacros These macros call a data structure dump of the object (`pointer`) in question.
 //dumpmacros `DUMP` is only available in *ALPHA* and *BETA* builds, `DUMP_IF` is also
-//dumpmacros enabled for the RELEASE builds.
+//dumpmacros enabled for RELEASE builds.
 //dumpmacros
 //dumpmacros `extra` is a void* which is transparently passed around and can be used to
-//dumpmacros pass some state around. NoBug does not touch it.
+//dumpmacros pass a particular state around. NoBug does not alter this.
 //dumpmacros
 */
 #define NOBUG_DUMP(flag, type, pointer, depth, extra)                                                           \
 //dumpmacros
 //dumpmacros Any output from `DUMP` handlers should be done by these macros.
 //dumpmacros
-//dumpmacros Dumping is by default done on level `LOG_DEBUG`, this can be overridden by
+//dumpmacros Dumping is by default done at `LOG_DEBUG` level, this can be overridden by
 //dumpmacros defining `NOBUG_DUMP_LEVEL` to some other level.
 //dumpmacros
 */
 #endif
 
 /*
-//logmacros HEAD- Logging Macros;;
+//logmacros HEAD- Macros That Log Information ;;
 //logmacros
-//logmacros Logging targets a flag (except for `ECHO`) and is done at a log-level relating to syslog levels.
+//logmacros Logging targets a flag (except for `ECHO`) and is done at a log-level related to syslog levels.
 //logmacros
-//logmacros NOTE: there is no logging macro for `LOG_EMERG`, this is only used by the assertions as fatal message
+//logmacros NOTE: there is no logging macro for `LOG_EMERG`, this is only used by the assertions as fatal message
 //logmacros
 //logmacros PARA ECHO; ECHO; unconditional logging for tests
 //logmacros  ECHO(...)
 //logmacros
 //logmacros Never optimized out, logs at LOG_NOTICE level. Its main purpose is for implementing
-//logmacros testsuites where one want to print and log messages independent of the build level
+//logmacros testsuites where one would like to print and log messages independent of the build level
 //logmacros
 */
 #define NOBUG_ECHO(...) \
 //logmacros  NOBUG_ALERT_CTX(flag, context, ...)
 //logmacros  NOBUG_ALERT_IF_CTX(when, flag, context, ...)
 //logmacros
-//logmacros This is the most critical condition an application might log. This might be used
-//logmacros if an error occurs which can not be handled except a safe shutdown for example.
+//logmacros This is the most critical condition that might be registered by 
+//logmacros an application. Situations might arise when the application  
+//logmacros encounters such a serious error that can only be adequately treated
+//logmacros by, for example, safely shutting down the application.
 //logmacros
 */
 #define NOBUG_ALERT(flag, ...) \
 //logmacros  NOBUG_ERROR_CTX(flag, context, ...)
 //logmacros  NOBUG_ERROR_IF_CTX(when, flag, context, ...)
 //logmacros
-//logmacros Application takes a error handling brach
+//logmacros This is used when an application registers an error
+//logmacros and appropriate action will have to be taken.
 //logmacros
 */
 #define NOBUG_ERROR(flag, ...) \
 //logmacros  NOBUG_WARN_CTX(flag, context, ...)
 //logmacros  NOBUG_WARN_IF_CTX(when, flag, context, ...)
 //logmacros
-//logmacros Rare, handled but unexpected branch
+//logmacros When an application encounters a rare and unexpected
+//logmacros situation, these macros can be used. 
 //logmacros
 */
 #define NOBUG_WARN(flag, ...) \
 //logmacros  NOBUG_INFO_CTX(flag, context, ...)
 //logmacros  NOBUG_INFO_IF_CTX(when, flag, context, ...)
 //logmacros
-//logmacros Message about program progress
+//logmacros It may be benificial to output information at various 
+//logmacros locations throughout the code, e.g., messages on programme
+//logmacros progress.
 //logmacros
 */
 #define NOBUG_INFO(flag, ...) \
 //logmacros  NOBUG_NOTICE_CTX(flag, context, ...)
 //logmacros  NOBUG_NOTICE_IF_CTX(when, flag, context, ...)
 //logmacros
-//logmacros More detailed progress message
+//logmacros Same as the INFO() macros, except more verbose.
 //logmacros
 */
 #define NOBUG_NOTICE(flag, ...) \
 //logmacros  NOBUG_TRACE_CTX(flag, context, ...)
 //logmacros  NOBUG_TRACE_IF_CTX(when, flag, context, ...)
 //logmacros
-//logmacros Very fine grained messages
+//logmacros The same as the NOTICE() macros, except very fine-grained information.
 //logmacros
-//logmacros NOTE: that `TRACE` corresponds to `LOG_DEBUG`, because using `DEBUG` could be ambiguous.
+//logmacros NOTE: `TRACE` corresponds to `LOG_DEBUG`, because using `DEBUG` could be ambiguous.
 //logmacros
 */
 #define NOBUG_TRACE(flag, ...) \
 //logmacros  NOBUG_LOG_CTX(flag, lvl, context, ...)
 //logmacros  NOBUG_LOG_IF_CTX(when, flag, lvl, context, ...)
 //logmacros
-//logmacros Generic logging macro which takes the level explicitly,
-//logmacros avoid this, unless you implement your own logging facilities.
+//logmacros Generic logging macro which takes the level explicitly.
+//logmacros Avoid this, unless you implement your own logging facilities.
 //logmacros
 */
 #define NOBUG_LOG_CTX(flag, lvl, context, ...) \
 //logmacros  NOBUG_LOG_BASELIMIT_RELEASE
 //logmacros  NOBUG_LOG_BASELIMIT
 //logmacros
-//logmacros anything more detailed than this base limits will be optimized out.
+//logmacros Anything more detailed than this base limits will be optimized out.
 //logmacros This is used to reduce the logging overhead for *RELEASE* builds.
 //logmacros By default the limit is set to `LOG_DEBUG` for *ALPHA* and *BETA*
 //logmacros builds, so all logging is retained and `LOG_NOTICE` in *RELEASE*
-//logmacros builds to log the application progress only coarsely then.
+//logmacros builds to log the application progress only coarsely.
 //logmacros
-//logmacros This macros can be defined before including 'nobug.h' to some other
+//logmacros These macros can be defined before including 'nobug.h' to some other
 //logmacros log level (as defined in 'syslog.h').
 //logmacros
 */
 #endif
 
 /*
-//annotations HEAD- Source Annotations;;
+//annotations HEAD- Source Code Annotations;;
 //annotations
-//annotations NoBug assists one with annotate properties and information to the code.
-//annotations This annotations may trigger compiletime or runtime notifications or errors,
-//annotations depending on the build level.
+//annotations Obsolete, buggy or precarious code can be marked in the code itself in 
+//annotations comments at the location where the code occurs.  However these code 
+//annotations locations can be easily overlooked, especially in large projects.  The
+//annotations advantage of this tagging scheme is that it provides an additional 
+//annotations instrument to alert or remind the programmer that there is still dubious 
+//annotations code embedded in the application. This tagging scheme not only informs
+//annotations the programmer at compile time that there is code in the application
+//annotations that needs attending to, but long after compilitation a test team
+//annotations might become aware of dubious code due to runtime messages.
+//annotations The action that should be taken when such a message occurs depends
+//annotations on the build level.
 //annotations
 */
 
                 alpha           beta            release
 DEPRECATED      log             nothing         wont compile
 
+//annotations
 //annotations PARA DEPRECATED; DEPRECATED; to be discarded in future
+//annotations
 //annotations  DEPRECATED(...)
 //annotations
-//annotations Something which shouldn't be used in future or productive code.
+//annotations Use this macro to identify code that is depreciated
+//annotations and should not be used in future or productive code.
 //annotations
 */
 #define NOBUG_DEPRECATED(...)                                                   \
@@ -733,8 +754,10 @@ UNIMPLEMENTED   abort           abort           wont compile
 //annotations PARA UNIMPLEMENTED; UNIMPLEMENTED; not yet implemented
 //annotations  UNIMPLEMENTED(...)
 //annotations
-//annotations Not yet finished vital feature, which must not be called.
-//annotations
+//annotations Use this macro to identify code that is functionally
+//annotations not yet complete and should not be used. This is convenient
+//annotations for code under development or being reviewed.
+//annotations 
 */
 #define NOBUG_UNIMPLEMENTED(...)                                                        \
   NOBUG_IF_NOT_RELEASE ( do {                                                           \
@@ -752,7 +775,7 @@ FIXME           log             wont compile    wont compile
 //annotations PARA FIXME; FIXME; known bug
 //annotations  FIXME(...)
 //annotations
-//annotations Known unfixed bug.
+//annotations Use this macro to mark a known and unfixed bug.
 //annotations
 */
 #define NOBUG_FIXME(...)                                                                \
@@ -788,7 +811,7 @@ PLANNED         log             nothing         nothing
 //annotations PARA PLANNED; PLANNED; ideas for future
 //annotations  PLANNED(...)
 //annotations
-//annotations Future enhancement, optimization to similar which has no sideeffect on the current program.
+//annotations Future enhancement, optimization to similar which has no side effect on the current program.
 //annotations
 */
 #define NOBUG_PLANNED(...)                                                              \
@@ -803,7 +826,7 @@ NOTREACHED      abort           abort           nothing
 //annotations PARA NOTREACHED; NOTREACHED; code path never taken
 //annotations  NOTREACHED(...)
 //annotations
-//annotations Code path which must never be reached.
+//annotations Code which must never be reached.
 //annotations
 */
 #define NOBUG_NOTREACHED(...)                                   \
@@ -818,7 +841,8 @@ NOTREACHED      abort           abort           nothing
 //annotations PARA ELSE_NOTREACHED; ELSE_NOTREACHED; alternative never taken
 //annotations  ELSE_NOTREACHED(...)
 //annotations
-//annotations same as `else NOTREACHED()`, but wholly optimized out in release builds.
+//annotations This macro is the same as `else NOTREACHED()`, but completely
+//annotations optimized out in release builds.
 //annotations
 */
 #define NOBUG_ELSE_NOTREACHED(...)                                      \