[vlc-devel] [PATCH 12/19] objects: move documentation to vlc_objects.h

[Kartik Ohri]

From: rustyc <amcap1712 at gmail.com>

Move documentation for VLC API methods vlc_list_children
from src/misc/objects.h to include/vlc_objects.h.
---
 include/vlc_objects.h | 24 ++++++++++++++++++++++++
 src/misc/objects.c    | 24 ------------------------
 2 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/include/vlc_objects.h b/include/vlc_objects.h
index 19ee5207fc..ffb3f09f21 100644
--- a/include/vlc_objects.h
+++ b/include/vlc_objects.h
@@ -135,6 +135,30 @@ VLC_API void *vlc_object_create( vlc_object_t *, size_t ) VLC_MALLOC VLC_USED;
 VLC_API void vlc_object_delete(vlc_object_t *obj);
 #define vlc_object_delete(obj) vlc_object_delete(VLC_OBJECT(obj))
 
+/**
+ * Lists the children of an object.
+ *
+ * Fills a table of pointers to children object of an object, incrementing the
+ * reference count for each of them.
+ *
+ * @param obj object whose children are to be listed
+ * @param tab base address to hold the list of children [OUT]
+ * @param max size of the table
+ *
+ * @return the actual numer of children (may be larger than requested).
+ *
+ * @warning The list of object can change asynchronously even before the
+ * function returns. The list meant exclusively for debugging and tracing,
+ * not for functional introspection of any kind.
+ *
+ * @warning Objects appear in the object tree early, and disappear late.
+ * Most object properties are not accessible or not defined when the object is
+ * accessed through this function.
+ * For instance, the object cannot be used as a message log target
+ * (because object flags are not accessible asynchronously).
+ * Also type-specific object variables may not have been created yet, or may
+ * already have been deleted.
+ */
 VLC_API size_t vlc_list_children(vlc_object_t *, vlc_object_t **, size_t) VLC_USED;
 
 /**
diff --git a/src/misc/objects.c b/src/misc/objects.c
index 7b15ae91d0..0c45be67c4 100644
--- a/src/misc/objects.c
+++ b/src/misc/objects.c
@@ -164,30 +164,6 @@ void vlc_object_Log(vlc_object_t *obj, int prio, const char *module,
     va_end(ap);
 }
 
-/**
- * Lists the children of an object.
- *
- * Fills a table of pointers to children object of an object, incrementing the
- * reference count for each of them.
- *
- * @param obj object whose children are to be listed
- * @param tab base address to hold the list of children [OUT]
- * @param max size of the table
- *
- * @return the actual numer of children (may be larger than requested).
- *
- * @warning The list of object can change asynchronously even before the
- * function returns. The list meant exclusively for debugging and tracing,
- * not for functional introspection of any kind.
- *
- * @warning Objects appear in the object tree early, and disappear late.
- * Most object properties are not accessible or not defined when the object is
- * accessed through this function.
- * For instance, the object cannot be used as a message log target
- * (because object flags are not accessible asynchronously).
- * Also type-specific object variables may not have been created yet, or may
- * already have been deleted.
- */
 size_t vlc_list_children(vlc_object_t *obj, vlc_object_t **restrict tab,
                          size_t max)
 {
-- 
2.25.1