Clarify which part of OBJ_MULTIPLE is not implemented, and under what case it

is perfectly fine to use.  (Inspired by a question I received about my last
commit.)

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@155244 65c4cc65-6c06-0410-ace0-fbb531ad65f3

diff --git a/include/asterisk/astobj2.h b/include/asterisk/astobj2.h
index f6b9a387fe26a5279d70ec0a96f293955725a3c8..a7a839c0fd008e1d491fcbb8758cbcd014fee026 100644 (file)
--- a/include/asterisk/astobj2.h
+++ b/include/asterisk/astobj2.h
@@ -511,7 +511,7 @@ Operations on container include:
     can be:
        OBJ_UNLINK - to remove the object, once found, from the container.
        OBJ_NODATA - don't return the object if found (no ref count change)
-       OBJ_MULTIPLE - don't stop at first match (not implemented)
+       OBJ_MULTIPLE - don't stop at first match (not fully implemented)
        OBJ_POINTER     - if set, 'arg' is an object pointer, and a hashtable
                   search will be done. If not, a traversal is done.
 
@@ -523,7 +523,7 @@ Operations on container include:
       - flags can be 
             OBJ_UNLINK   - to remove the object, once found, from the container.
             OBJ_NODATA   - don't return the object if found (no ref count change)
-            OBJ_MULTIPLE - don't stop at first match (not implemented)
+            OBJ_MULTIPLE - don't stop at first match (not fully implemented)
             OBJ_POINTER  - if set, 'arg' is an object pointer, and a hashtable
                         search will be done. If not, a traversal is done through
                         all the hashtable 'buckets'..
@@ -615,7 +615,10 @@ enum search_flags {
         *  its refcount. */
        OBJ_NODATA       = (1 << 1),
        /*! Don't stop at the first match in ao2_callback()
-        *  \note This is not fully implemented. */
+        *  \note This is not fully implemented.   Using OBJ_MULTIME with OBJ_NODATA
+        *  is perfectly fine.  The part that is not implemented is the case where
+        *  multiple objects should be returned by ao2_callback().
+        */
        OBJ_MULTIPLE = (1 << 2),
        /*! obj is an object of the same type as the one being searched for,
         *  so use the object's hash function for optimized searching.