From 33bc94eb209864b4aef7f341f0c2b7cd8740396f Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Fri, 10 May 2013 14:16:35 +0200 Subject: [PATCH] qom: improve documentation of cast functions Signed-off-by: Paolo Bonzini Message-id: 1368188203-3407-2-git-send-email-pbonzini@redhat.com Signed-off-by: Anthony Liguori --- 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); -- 2.7.4