git commit: Doxygenated ink_zero

[am...@apache.org]

Updated Branches:
  refs/heads/master 23af5c5b5 -> 3ae28350f


Doxygenated ink_zero


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/3ae28350
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/3ae28350
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/3ae28350

Branch: refs/heads/master
Commit: 3ae28350fc3771630a28929a84184f407e7d0e25
Parents: 23af5c5
Author: Alan M. Carroll <am...@network-geographics.com>
Authored: Mon Jan 30 13:00:41 2012 -0600
Committer: Alan M. Carroll <am...@network-geographics.com>
Committed: Mon Jan 30 13:00:41 2012 -0600

----------------------------------------------------------------------
 lib/ts/ink_memory.h |   39 ++++++++++++++++++++++++++++++++++-----
 1 files changed, 34 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/3ae28350/lib/ts/ink_memory.h
----------------------------------------------------------------------
diff --git a/lib/ts/ink_memory.h b/lib/ts/ink_memory.h
index 1f2386c..bb6f48c 100644
--- a/lib/ts/ink_memory.h
+++ b/lib/ts/ink_memory.h
@@ -57,13 +57,42 @@ extern "C"
 
 #ifdef __cplusplus
 }
+#endif
+
+#ifdef __cplusplus
+/** Set data to zero.
+
+    Calls @c memset on @a t with a value of zero and a length of @c
+    sizeof(t). This can be used on ordinary and array variables. While
+    this can be used on builtin values it's inefficient.
+
+    @note Because this uses templates it cannot be used on unnamed or
+    locally scoped structures / classes. This is an inherent
+    limitation of templates.
+
+    Examples:
+    @code
+    foo bar; // value.
+    ink_zero(bar); // zero bar.
 
-template < typename T >
-T& ink_zero(T& t) {
+    foo *bar; // pointer.
+    ink_zero(bar); // WRONG - makes the pointer @a bar zero.
+    ink_zero(*bar); // zero what bar points at.
+
+    foo bar[ZOMG]; // Array of structs.
+    ink_zero(bar); // Zero all structs in array.
+
+    foo *bar[ZOMG]; // array of pointers.
+    ink_zero(bar); // zero all pointers in the array.
+    @endcode
+    
+ */
+template < typename T > inline void
+ink_zero(
+	 T& t ///< Object to zero.
+	 ) {
   memset(&t, 0, sizeof(t));
-  return t;
 }
-
-#endif                          /* __cplusplus */
+#endif  /* __cplusplus */
 
 #endif