More documentation fixes, formatting, cosmetic, wording
authorChristian Thaeter <ct@pipapo.org>
Tue, 17 Aug 2010 23:22:12 +0000 (01:22 +0200)
committerChristian Thaeter <ct@pipapo.org>
Tue, 17 Aug 2010 23:22:12 +0000 (01:22 +0200)
12 files changed:
doc/annotationtable.txt
doc/buildinstall.txt
doc/dumpexample.txt
doc/dumping.txt
doc/initialization.txt
doc/logconfiguration.txt
doc/logflags.txt
doc/logflagsenv.txt
doc/macros.txt
doc/multithreading.txt
doc/resourceexample.txt
src/nobug.h

index b111367..8b21ae1 100644 (file)
@@ -1,4 +1,8 @@
 
+HEAD~ Annotation Semantics; annotations, semantics; actions taken on annotations
+
+The action that should be taken when an annotated source line is reached
+depends on the build level.
 
 [frame="topbot",options="header"]
 |================================================
index fc5a124..755351e 100644 (file)
@@ -15,14 +15,16 @@ some features are not available or degraded.
 |x86    |other Linux |gcc4        |supported footnote:[Please report distro specific problems]
 |armel  |maemo5      |gcc4        |supported footnote:[check fails in SDK (emulator bug)]
 |x86*   |Mac OS X    |gcc4        |supported
-|x86    |OpenSolaris |gcc4, suncc |mostly    footnote:[Builds, but target check fails]
+|x86    |OpenSolaris |gcc4        |supported
+|x86    |OpenSolaris |suncc       |mostly    footnote:[some features are not
+available, needs more testing]
 |       |*BSD        |            |planned   footnote:[Need volunteer for testing]
 |=================================================================================
 
 NoBug has few mandatory dependencies on other software and libraries,
 some things such as valgrind support are optional and should be automatially
 detected by `./configure`. Nevertheless it
-requires 'pkg-config' to be installed or you'll get some weird errors at 
+requires 'pkg-config' to be installed or you'll get some weird errors at
 bootstrapping (`autoreconf`) already.
 
 
index a01076c..07c0918 100644 (file)
@@ -20,21 +20,25 @@ nobug_STRUCTNAME_dump (const struct STRUCTNAME* self,
                        const struct nobug_context context,
                        void* extra)
 {
-  // check for self != NULL and that the depth
-  // limit was not exceeded in recursive data structures
+  /* check for self != NULL and that the depth limit
+     was not exceeded in recursive data structures */
   if (self && depth)
   {
-    // you may or may not do something with the extra parameter here
-    // extra is transparently passed around
+    /* you may or may not do something with the extra
+       parameter here, extra is transparently
+       passed around */
     (void) extra;
 
-    // use DUMP_LOG not LOG to print the data
+    /* use DUMP_LOG not LOG to print the data */
     DUMP_LOG("STRUCTNAME %p: int is %d, string is %s", self,
                              self->INTEGER_MEMBER,
                              self->STRING_MEMBER);
 
-    // now recurse with decremented depth
-    nobug_STRUCTNAME_dump (self->next, depth-1, context, extra);
+    /* now recurse while decrementing depth */
+    nobug_STRUCTNAME_dump (self->next,
+                           depth-1,
+                           context,
+                           extra);
   }
 }
 -------------------------------------------------------
@@ -48,7 +52,8 @@ example()
   struct STRUCTNAME foo;
   init(&foo);
 
-  // extra can be anything, NULL is suggested when you don't use it
+  /* extra can be anything,
+     NULL is suggested when you don't use it */
   DUMP (my_flag, STRUCTNAME, &foo, 2, NULL);
 }
 -------------------------------------------------------
index 13341a7..10430a6 100644 (file)
@@ -1,7 +1,5 @@
 HEAD- Dumping Data Structures;dumping;
 
-TODO How to write DUMP handlers
-
 One can write functions to dump complex data structures using the NoBug
 facilities. This is done by writing a custom function for each
 data structure to be dumped, which may recursively call other dumping
@@ -25,3 +23,4 @@ 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
 that you can use to store some additional state.
+
index 586183e..0ac39ab 100644 (file)
@@ -47,13 +47,13 @@ HEAD== Threads;;
 
 In Multithreaded programs you should assign an identifier to each
 thread. A thread identifier is a string which will be automatically
-appended with an underscore and an incrementing integer. It is is 
+appended with an underscore and an incrementing integer. It is is
 created using the following:
 
   NOBUG_THREAD_ID_SET(name)
 
-Calling `NOBUG_THREAD_ID_SET("worker")` will yield in a thread
-identifier 'worker_1' for example.
+For example, calling `NOBUG_THREAD_ID_SET("worker")` will result in a thread
+identifier 'worker_1'.
 
 If you don't set an identifier, then NoBug will automatically assign
 one.  This is further documented in the xref:multithreading[multi threading]
@@ -62,11 +62,11 @@ section of this manual.
 
 PARA Initialization example; initexample; initialize NoBug, example
 
-Thus the boilerplate code to pulling up NoBug looks like:
-
+Thus the boilerplate code to pulling up NoBug in a multithreaded program looks
+like (omit `NOBUG_THREAD_ID_SET()` in single threaded programs):
 [source,C]
 -------------------------------------------------------
-#include "nobug.h"
+#include <nobug.h>
 NOBUG_DEFINE_FLAG(example);
 
 ...
index e66236b..af4706f 100644 (file)
@@ -6,16 +6,15 @@ Each log macro has an explicit or implicit log-level which
 correspondends to syslog levels. Logging is only emitted when the
 message is more severe or the same as a defined limit.
 
-[[logdefaults]]
-.Default levels for logging
-[cols="h,4*",frame="topbot",options="header"]
+INDEX Default levels for logging; logging level defaults; table showing defaults log levels
+[frame="topbot",options="header"]
 |===============================================================================
-|            |ALPHA    |BETA    |RELEASE |
-|ringbuffer  |TRACE    |INFO    |NOTICE  |ringbuffer must always be most verbose
-|console     |INFO     |NOTICE  |-1      |no log to console in release
-|file        |TRACE    |NOTICE  |WARNING |
-|syslog      |-1       |NOTICE  |WARNING |no syslog for test runs
-|application |INFO     |WARNING |ERROR   |
+|            |ALPHA    |BETA    |RELEASE
+|ringbuffer footnote:[ringbuffer must always be most verbose] |TRACE    |INFO    |NOTICE
+|console     |INFO     |NOTICE  |-1 footnote:[no log to console in release]
+|file        |TRACE    |NOTICE  |WARNING
+|syslog      |-1 footnote:[no syslog for test runs]      |NOTICE  |WARNING
+|application |INFO     |WARNING |ERROR
 |===============================================================================
 
 Depending on the build level, there is a default logging target and a default
index d01f419..5cfdc3f 100644 (file)
@@ -6,9 +6,9 @@ logging libraries.
 
 Flags are generally used as follows:
 
-    * Declare the flag.
-    * Define the flag.
-    * Initialise the flag.
+    . Declare the flag.
+    . Define the flag.
+    . Initialise the flag.
 
 To declare a flag, it is suggested to do so in a header file:
 INDEX DECLARE_FLAG; DECLARE_FLAG; declaring a flag
@@ -37,7 +37,7 @@ INDEX DEFINE_FLAG_PARENT_LIMIT; DEFINE_FLAG_PARENT_LIMIT; defining a flag hierar
 
  NOBUG_DEFINE_FLAG_PARENT_LIMIT(flagname, parent, limit)
 
-This can be used to create hierachies of flags.
+This can be used to create hierarchies of flags.
 
 
 HEAD^ C\++ support, C++ logflags; Cplusplus_logflags; C\++ support for log flags
@@ -111,7 +111,7 @@ This macros will parse the '$NOBUG_LOG' envirionment variable at runtime
 initializing the given flag dynamically.
 
 For flags defined with `NOBUG_DEFINE_FLAG(flagname)` the defaults are
-initialized as in the xref:logdefaults[table above], while
+initialized as in the xref:loggingleveldefaults[table above], while
 `NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the default
 target (depending on build level) to `level`.
 
index 0b4f1a6..fdd86d4 100644 (file)
@@ -19,14 +19,15 @@ targetdecl --> '@', "targetname", opt(targetopts).
 targetopts --> '(', "options for target", ')', opt(targetopts).
 ----
 
-Roughly speaking, '$NOBUG_LOG' contains a comma separated list of declarations for
-flags, which is the name of the flag followed by a limit which is all written in
-uppercase letters and preceeded by a colon, followed by target declarations
-which are the names of targets, introduced by an at sign. Target declarations
-can have options, which are described in the next section. Limit and target
-declarations are optional and defaults are selected from the table above. The
-defaults presented here are currently an approximation of what might be viable.
-The default values used here may be redefined in a future release.
+Roughly speaking, '$NOBUG_LOG' contains a comma separated list of declarations
+for flags, which is the name of the flag followed by a limit which is all
+written in uppercase letters and preceeded by a colon, followed by target
+declarations which are the names of targets, introduced by an at sign. Target
+declarations can have options, which are described in the next section. Limit
+and target declarations are optional and defaults are selected from the
+xref:loggingleveldefaults[table above]. The defaults presented here are
+currently an approximation of what might be viable. The default values used
+here may be redefined in a future release.
 
 HEAD^ Targets and Options; logging options; configure what gets logged
 
@@ -45,8 +46,9 @@ The Following options are available:
   `(temp)`:::
     unlink file instantly at creation
 
-The default ringbuffer is a temporary file in `/tmp` with the `temp` option.
-This means it will not be accessible.
+The default ringbuffer is a temporary file in '/tmp' with the `temp` option.
+This means it will not be available and accessible for inspection, but it also
+won't leave any stale data behind when the application ends.
 
 
 `@console`::
index d138d92..95d7ac4 100644 (file)
@@ -7,6 +7,7 @@ log information on the current file, line number and function.
 Moreover, all the flat namespace uppercase identifiers make it easy
 to recognise the macros in source code.
 
+INDEX DISABLE_SHORTNAMES; DISABLE_SHORTNAMES; require NOBUG_ prefix everywhere
 All macros are available without condition with a `NOBUG_...` prefix. Many
 macros (the common cases) are also available without this prefix as a
 convenience, however macros without this prefix must not have been previously
@@ -25,10 +26,10 @@ They perform the desired action only if `when` is true. For example:
 
 The assertion will only be performed if `foo` is non `NULL`.
 
-NoBug also contains a facility to pass the source context (file,
-line, function) around, this can be used to write functions which
-handle things where one is more interested in the context of the caller
-rather than the location where the macro appears.
+NoBug also contains a facility to pass the xref:NOBUGCONTEXT[source context]
+(file, line, function) around, this can be used to write functions which
+handle things where one is more interested in the context of the caller rather
+than the location where the macro appears.
 
 These macros are postfixed with `..._CTX` and take an extra context
 parameter (usually at last but before the logging format specifier and
index 8ad9afb..5bd73d4 100644 (file)
@@ -35,7 +35,7 @@ PARA NOBUG_THREAD_DATA; THREAD_DATA; thread local data for application use
  NOBUG_THREAD_DATA
 
 Evaluates to a variable of type `void*` which can be used to store
-thread local information. This is useable for xref:_callbacks[callbacks] which may
+thread local information. This is useable for xref:callbacks[callbacks] which may
 prepare context information to be reused later.
 
 This macro is also available in singlethreaded programs, refering to a
index 42a7f3c..f1c72c2 100644 (file)
@@ -5,37 +5,44 @@ NOBUG_DEFINE_FLAG_LIMIT(test, LOG_DEBUG);
 
 void example()
 {
-  // define a mutex and announce it
+  /* define a mutex and announce it */
   pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
   RESOURCE_HANDLE(resource);
 
-  // 'example' is just a pointer to this function which suffices as unique id
-  RESOURCE_ANNOUNCE(test, "mutex", "my_mutex", example, resource);
+  /* 'example' is just a pointer to this function
+     which suffices as unique identifier */
+  RESOURCE_ANNOUNCE(test, "mutex", "my_mutex",
+                    example, resource);
 
-  // the following would be done in a different thread in a real program
-  // define a handle
+  /* the following would be done in a
+     different thread in a real program */
+
+  /* define a handle */
   RESOURCE_HANDLE(enter);
 
-  // announce that we want to use the resource
-  // &enter also suffices as unique pointer, which is all we need as identifer here
+  /* announce that we want to use the resource
+     &enter also suffices as unique pointer,
+     which is all we need as identifer here */
   RESOURCE_WAIT(flag, resource, &enter, enter)
     {
-      // lock() might block
+      /* lock() might block */
       pthread_mutex_lock (&my_mutex);
-      // assume no errors, got it, change the state
+      /* assume no errors, got it, change the state */
       RESOURCE_STATE(test, NOBUG_RESOURCE_EXCLUSIVE, enter);
     }
 
-  ////////////////////////////////////////
-  // program does something useful here //
-  ////////////////////////////////////////
+  /***************************************
+  ** program does something useful here **
+  ***************************************/
 
-  // we don't need it anymore
-  RESOURCE_LEAVE(test, enter)  // << no semicolon
+  /* we don't need it anymore */
+  RESOURCE_LEAVE(test, enter)  /* << no semicolon! */
     pthread_mutex_unlock (&my_mutex);
 
-  // back in the main thread
-  RESOURCE_FORGET(test, resource);                         // remove the resource from the public registry
+  /* back in the main thread */
+
+  /* remove the resource from the public registry */
+  RESOURCE_FORGET(test, resource);
 }
 ----
 
index 6127f80..80d6e2d 100644 (file)
 //assertions
 //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 but have not effect in *RELEASE* builds.
 //assertions
 */
 #define NOBUG_REQUIRE(expr, ...) \
 //assertions
 //assertions Postcondition (progress/output) check. Use these macros to validate the
 //assertions data a function produces (example: return value). `ENSURE` is enabled
-//assertions unconditionally in *ALPHA* builds and optimized out in *BETA* builds for
+//assertions unconditionally in *ALPHA* builds and have no effect in *BETA* builds for
 //assertions scopes which are tagged as `CHECKED`.
 //assertions
 //assertions The `ENSURE_IF` variants are enabled in *ALPHA* and *BETA* builds.
 //assertions
-//assertions In *RELEASE* builds these checks are
-//assertions never available. Scopes tagged as `UNCHECKED` are not permitted.
+//assertions In *RELEASE* builds these checks are optimized out.
 //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. 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 which doesn't fall into one of the above categories. Generally to be
+//assertions avoided! The checks are enabled in *ALPHA* and *BETA* builds and
+//assertions have no effect in *RELEASE* builds.
 //assertions
 */
 #define NOBUG_ASSERT(expr, ...) \
 //dumpmacros  DUMP_IF(when, flag, type, pointer, depth, extra)
 //dumpmacros
 //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 `DUMP` has only effect in *ALPHA* and *BETA* builds, `DUMP_IF` is also
 //dumpmacros enabled for RELEASE builds.
 //dumpmacros
 //dumpmacros `extra` is a void* which is transparently passed around and can be used to
 //dumpmacros
 //dumpmacros Any output from `DUMP` handlers should be done by these macros.
 //dumpmacros
-//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
 */
-
 #define NOBUG_DUMP_LOG(...)                             \
   NOBUG_LOG_( &nobug_flag_NOBUG_ON, NOBUG_DUMP_LEVEL,   \
               "DUMP", dump_context,                     \
   )
 
 
+/*
+//dumpmacros PARA DUMP_LEVEL; DUMP_LEVEL; logging level at which DUMPs are done
+//dumpmacros
+//dumpmacros  #define NOBUG_DUMP_LEVEL ...
+//dumpmacros
+//dumpmacros Dumping is by default done at `LOG_DEBUG` level, this can be overridden by
+//dumpmacros defining `NOBUG_DUMP_LEVEL` to some other logging level.
+//dumpmacros
+*/
 #ifndef NOBUG_DUMP_LEVEL
 #define NOBUG_DUMP_LEVEL LOG_DEBUG
 #endif
 
+
 /*
 //logmacros HEAD- Macros That Log Information ;;
 //logmacros
 //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 a fatal message
-//logmacros
 //logmacros PARA ECHO; ECHO; unconditional logging for tests
 //logmacros
 //logmacros  ECHO(...)
 #define NOBUG_ECHO(...) \
   NOBUG_LOG_(&nobug_flag_NOBUG_ANN, LOG_NOTICE, "ECHO", NOBUG_CONTEXT, ""__VA_ARGS__)
 
+
 /*
 //logmacros PARA ALERT; ALERT; about to die
 //logmacros
 //logmacros  NOBUG_TRACE_IF_CTX(when, flag, context, ...)
 //logmacros
 //logmacros The same as the NOTICE() macros, except very fine-grained information.
+//logmacros a common use case is to put just `TRACE(debugflag)` just at the begin of every
+//logmacros non-trivial function. This allows to see fine grained application progress in the log.
 //logmacros
 //logmacros NOTE: `TRACE` corresponds to `LOG_DEBUG`, because using `DEBUG` could be ambiguous.
 //logmacros
     NOBUG_LOG_CTX(flag, lvl, context, ""__VA_ARGS__)    \
   )
 
+/*
+//logmacros INDEX LOG_EMERG; LOG_EMERG; no logging macro for emergency logging
+//logmacros
+//logmacros NOTE: there is no logging macro for `LOG_EMERG`, this is only used by the assertions as a fatal message
+//logmacros
+*/
 
 /*
   low level logging handler
 //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
 */
 
@@ -2243,7 +2251,11 @@ NOBUG_IFNOT(NOBUG_USE_VALGRIND, 0)
 //toolmacros Sometimes it is useful to have initializer code only in *ALPHA* builds, for example when you
 //toolmacros conditionally include resource handles only in *ALPHA* versions. An initializer can then
 //toolmacros use this macros to append a comman and something else only in *ALPHA* builds as in:
-//toolmacros  struct foo = {"foo", "bar" NOBUG_ALPHA_COMMA_NULL };
+//toolmacros
+//toolmacros [source,C]
+//toolmacros ----
+//toolmacros struct foo = {"foo", "bar" NOBUG_ALPHA_COMMA_NULL };
+//toolmacros ----
 //toolmacros
 */
 #define NOBUG_COMMA ,
@@ -2721,7 +2733,7 @@ extern struct nobug_flag nobug_flag_NOBUG_ANN;
 extern struct nobug_flag nobug_flag_nobug;
 extern unsigned long long nobug_counter;
 
-//callbacks HEAD- Callbacks;;
+//callbacks HEAD- Callbacks; callbacks; function hooks to catch nobug actions
 //callbacks
 //callbacks NoBug provides callbacks, applications can use these
 //callbacks to present logging information in some custom way or hook some special processing in.
@@ -2731,10 +2743,12 @@ extern unsigned long long nobug_counter;
 //callbacks CAUTION: There are certain constraints what and what not can be done in callbacks
 //callbacks          documented below which must be followed.
 //callbacks
-//callbacks PARA type of logging callbacks; logging_cb; type of a logging callback function
-typedef void (*nobug_logging_cb)(const struct nobug_flag* flag, int priority, const char *log, void* data);     //callbacks  VERBATIM;
+//callbacks PARA logging callback functiontype; logging_cb; type of a logging callback function
 //callbacks
-//callbacks used for the logging callbacks
+typedef void (*nobug_logging_cb)(const struct nobug_flag* flag,         //callbacks  VERBATIM;
+                                 int priority,                          //callbacks  VERBATIM;
+                                 const char *log,                       //callbacks  VERBATIM;
+                                 void* data);                           //callbacks  VERBATIM;
 //callbacks
 //callbacks  `flag`::
 //callbacks     Flag structure which defines the logging configuration for this event
@@ -2746,16 +2760,16 @@ typedef void (*nobug_logging_cb)(const struct nobug_flag* flag, int priority, co
 //callbacks     Global pointer defined by the user, passed arround (see below)
 //callbacks
 
-//callbacks PARA type of abort callback; abort_cb; type of a abort callback function
-typedef void (*nobug_abort_cb)(void* data);             //callbacks  VERBATIM;
+//callbacks PARA abort callback functiontype; abort_cb; type of a abort callback function
 //callbacks
-//callbacks used for the abort callback
+typedef void (*nobug_abort_cb)(void* data);             //callbacks  VERBATIM;
 //callbacks
 //callbacks  `data`::
 //callbacks     Global data defined by the user, passed arround (see below)
 //callbacks
 
 //callbacks PARA passing data to callbacks; callback_data; data to be passed to callbacks
+//callbacks
 extern
 void* nobug_callback_data;                              //callbacks  VERBATIM;
 //callbacks
@@ -2764,6 +2778,7 @@ void* nobug_callback_data;                              //callbacks  VERBATIM;
 //callbacks
 
 //callbacks PARA callback when logging; logging_callback; hook when something get logged
+//callbacks
 extern
 nobug_logging_cb nobug_logging_callback;                //callbacks  VERBATIM;
 //callbacks
@@ -2782,6 +2797,7 @@ nobug_logging_cb nobug_logging_callback;                //callbacks  VERBATIM;
 //callbacks
 
 //callbacks PARA callback after logging; postlogging_callback; hook after something get logged
+//callbacks
 extern
 nobug_logging_cb nobug_postlogging_callback;            //callbacks  VERBATIM;
 //callbacks
@@ -2793,6 +2809,7 @@ nobug_logging_cb nobug_postlogging_callback;            //callbacks  VERBATIM;
 //callbacks
 
 //callbacks PARA callback for aborting; abort_callback; hook to handle a termination
+//callbacks
 extern
 nobug_abort_cb nobug_abort_callback;            //callbacks  VERBATIM;
 //callbacks