improve the annotations doc
authorChristian Thaeter <ct@pipapo.org>
Mon, 9 Aug 2010 06:12:10 +0000 (08:12 +0200)
committerChristian Thaeter <ct@pipapo.org>
Mon, 9 Aug 2010 06:12:10 +0000 (08:12 +0200)
src/nobug.h

index fb1a257..92292b9 100644 (file)
 /*
 //annotations HEAD- Source Annotations;;
 //annotations
-//annotations One can tag features as:
+//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
 */
 
@@ -714,7 +716,7 @@ DEPRECATED      log             nothing         wont compile
 //annotations PARA DEPRECATED; DEPRECATED; to be discarded in future
 //annotations  DEPRECATED(...)
 //annotations
-//annotations Something which shouldn't be used in future
+//annotations Something which shouldn't be used in future or productive code.
 //annotations
 */
 #define NOBUG_DEPRECATED(...)                                                   \
@@ -731,7 +733,7 @@ UNIMPLEMENTED   abort           abort           wont compile
 //annotations PARA UNIMPLEMENTED; UNIMPLEMENTED; not yet implemented
 //annotations  UNIMPLEMENTED(...)
 //annotations
-//annotations not yet finished feature
+//annotations Not yet finished vital feature, which must not be called.
 //annotations
 */
 #define NOBUG_UNIMPLEMENTED(...)                                                        \
@@ -750,7 +752,7 @@ FIXME           log             wont compile    wont compile
 //annotations PARA FIXME; FIXME; known bug
 //annotations  FIXME(...)
 //annotations
-//annotations known bug to be fixed later
+//annotations Known unfixed bug.
 //annotations
 */
 #define NOBUG_FIXME(...)                                                                \
@@ -767,7 +769,7 @@ TODO            log             log             wont compile
 //annotations PARA TODO; TODO; things to be done
 //annotations  TODO(...)
 //annotations
-//annotations enhancement to be done soon
+//annotations Enhancement or non-critical bug to be done soon.
 //annotations
 */
 #define NOBUG_TODO(...)                                                         \
@@ -786,7 +788,7 @@ PLANNED         log             nothing         nothing
 //annotations PARA PLANNED; PLANNED; ideas for future
 //annotations  PLANNED(...)
 //annotations
-//annotations future enhancement
+//annotations Future enhancement, optimization to similar which has no sideeffect on the current program.
 //annotations
 */
 #define NOBUG_PLANNED(...)                                                              \
@@ -801,7 +803,7 @@ NOTREACHED      abort           abort           nothing
 //annotations PARA NOTREACHED; NOTREACHED; code path never taken
 //annotations  NOTREACHED(...)
 //annotations
-//annotations used to tag code-path which shall be never executed.
+//annotations Code path which must never be reached.
 //annotations
 */
 #define NOBUG_NOTREACHED(...)                                   \
@@ -830,7 +832,7 @@ NOTREACHED      abort           abort           nothing
 /*
 //faultinjection HEAD- Fault injection;;
 //faultinjection
-//faultinjection NoBug has some macros which can be used to simulate errorneous behaviour:
+//faultinjection NoBug has some macros which can be used to simulate errorneous behaviour.
 //faultinjection
 //faultinjection PARA INJECT_GOODBAD; INJECT_GOODBAD; fault injection expression
 //faultinjection  INJECT_GOODBAD(expr, good, bad)
@@ -857,7 +859,7 @@ NOTREACHED      abort           abort           nothing
 
 
 /*
-//faultinjection PARA INJECT_LEVEL; INJECT_LEVEL; log level for fault injection
+//faultinjection PARA Setting the logging level for fault injections; INJECT_LEVEL; log level for fault injection
 //faultinjection In both cases, when a fault is injected it will be logged at
 //faultinjection `NOBUG_INJECT_LEVEL` (default: `LOG_NOTICE`). This can be defined
 //faultinjection before including 'nobug.h' to override it.