[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH for-1.5 1/9] qom: improve documentation of cast func
From: |
Paolo Bonzini |
Subject: |
[Qemu-devel] [PATCH for-1.5 1/9] qom: improve documentation of cast functions |
Date: |
Fri, 10 May 2013 14:16:35 +0200 |
Signed-off-by: Paolo Bonzini <address@hidden>
---
include/qom/object.h | 23 +++++++++++++++++++++--
1 file changed, 21 insertions(+), 2 deletions(-)
diff --git a/include/qom/object.h b/include/qom/object.h
index d0f99c5..41b7068 100644
--- a/include/qom/object.h
+++ b/include/qom/object.h
@@ -612,7 +612,8 @@ Object *object_dynamic_cast(Object *obj, const char
*typename);
*
* See object_dynamic_cast() for a description of the parameters of this
* function. The only difference in behavior is that this function asserts
- * instead of returning #NULL on failure.
+ * instead of returning #NULL on failure. This function is not meant to be
+ * called directly, but only through the wrapper macro OBJECT_CHECK.
*/
Object *object_dynamic_cast_assert(Object *obj, const char *typename);
@@ -659,11 +660,29 @@ Type type_register(const TypeInfo *info);
* @klass: The #ObjectClass to attempt to cast.
* @typename: The QOM typename of the class to cast to.
*
- * Returns: This function always returns @klass and asserts on failure.
+ * See object_class_dynamic_cast() for a description of the parameters
+ * of this function. The only difference in behavior is that this function
+ * asserts instead of returning #NULL on failure. This function is not
+ * meant to be called directly, but only through the wrapper macros
+ * OBJECT_CLASS_CHECK and INTERFACE_CHECK.
*/
ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass,
const char *typename);
+/**
+ * object_class_dynamic_cast:
+ * @klass: The #ObjectClass to attempt to cast.
+ * @typename: The QOM typename of the class to cast to.
+ *
+ * Returns: If @typename is a class, this function returns @klass if
+ * @typename is a subtype of @klass, else returns #NULL.
+ *
+ * If @typename is an interface, this function returns the interface
+ * definition for @klass if @klass implements it unambiguously; #NULL
+ * is returned if @klass does not implement the interface or if multiple
+ * classes or interfaces on the hierarchy leading to @klass implement
+ * it. (FIXME: perhaps this can be detected at type definition time?)
+ */
ObjectClass *object_class_dynamic_cast(ObjectClass *klass,
const char *typename);
--
1.8.1.4
- [Qemu-devel] [PATCH for-1.5 0/9] Disable expensive QOM cast debugging for official releases, Paolo Bonzini, 2013/05/10
- [Qemu-devel] [PATCH for-1.5 1/9] qom: improve documentation of cast functions,
Paolo Bonzini <=
- [Qemu-devel] [PATCH for-1.5 2/9] qom: allow casting of a NULL class, Paolo Bonzini, 2013/05/10
- [Qemu-devel] [PATCH for-1.5 3/9] qom: add a fast path to object_class_dynamic_cast, Paolo Bonzini, 2013/05/10
- [Qemu-devel] [PATCH for-1.5 4/9] qom: pass file/line/function to asserting casts, Paolo Bonzini, 2013/05/10
- [Qemu-devel] [PATCH for-1.5 5/9] qom: trace asserting casts, Paolo Bonzini, 2013/05/10
- [Qemu-devel] [PATCH for-1.5 7/9] build: disable QOM cast debugging for official releases, Paolo Bonzini, 2013/05/10
- [Qemu-devel] [PATCH for-1.5 6/9] qom: allow turning cast debugging off, Paolo Bonzini, 2013/05/10
- [Qemu-devel] [PATCH for-1.5 8/9] qom: simplify object_class_dynamic_cast, part 1, Paolo Bonzini, 2013/05/10
- [Qemu-devel] [PATCH for-1.5 9/9] qom: simplify object_class_dynamic_cast, part 2, Paolo Bonzini, 2013/05/10
- Re: [Qemu-devel] [PATCH for-1.5 0/9] Disable expensive QOM cast debugging for official releases, Anthony Liguori, 2013/05/10