From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([208.118.235.92]:39902) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UamFo-0003hN-VQ for qemu-devel@nongnu.org; Fri, 10 May 2013 08:16:54 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UamFn-0007ik-Ic for qemu-devel@nongnu.org; Fri, 10 May 2013 08:16:52 -0400 Received: from mail-we0-x236.google.com ([2a00:1450:400c:c03::236]:64802) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UamFn-0007id-DG for qemu-devel@nongnu.org; Fri, 10 May 2013 08:16:51 -0400 Received: by mail-we0-f182.google.com with SMTP id t60so3928414wes.41 for ; Fri, 10 May 2013 05:16:50 -0700 (PDT) Sender: Paolo Bonzini From: Paolo Bonzini Date: Fri, 10 May 2013 14:16:35 +0200 Message-Id: <1368188203-3407-2-git-send-email-pbonzini@redhat.com> In-Reply-To: <1368188203-3407-1-git-send-email-pbonzini@redhat.com> References: <1368188203-3407-1-git-send-email-pbonzini@redhat.com> Subject: [Qemu-devel] [PATCH for-1.5 1/9] qom: improve documentation of cast functions List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: Anthony Liguori , Andreas Faerber , Aurelien Jarno , mst@redhat.com Signed-off-by: Paolo Bonzini --- 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