From: Aaron Ballman Date: Wed, 19 Feb 2014 15:45:13 +0000 (+0000) Subject: Moving the documentation for the objc_requires_super attribute into AttrDocs. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=90ec5ff217d0a13279483131d463b2f55ebaf2f3;p=clang Moving the documentation for the objc_requires_super attribute into AttrDocs. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@201687 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst index a6008b2adc..e7a38053af 100644 --- a/docs/LanguageExtensions.rst +++ b/docs/LanguageExtensions.rst @@ -1195,52 +1195,6 @@ feature, clang provides default synthesis of those properties not declared ``__has_feature(objc_default_synthesize_properties)`` checks for availability of this feature in version of clang being used. -.. _langext-objc_method_family: - - -Objective-C requiring a call to ``super`` in an override --------------------------------------------------------- - -Some Objective-C classes allow a subclass to override a particular method in a -parent class but expect that the overriding method also calls the overridden -method in the parent class. For these cases, we provide an attribute to -designate that a method requires a "call to ``super``" in the overriding -method in the subclass. - -**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only -be placed at the end of a method declaration: - -.. code-block:: objc - - - (void)foo __attribute__((objc_requires_super)); - -This attribute can only be applied the method declarations within a class, and -not a protocol. Currently this attribute does not enforce any placement of -where the call occurs in the overriding method (such as in the case of -``-dealloc`` where the call must appear at the end). It checks only that it -exists. - -Note that on both OS X and iOS that the Foundation framework provides a -convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this -attribute: - -.. code-block:: objc - - - (void)foo NS_REQUIRES_SUPER; - -This macro is conditionally defined depending on the compiler's support for -this attribute. If the compiler does not support the attribute the macro -expands to nothing. - -Operationally, when a method has this annotation the compiler will warn if the -implementation of an override in a subclass does not call super. For example: - -.. code-block:: objc - - warning: method possibly missing a [super AnnotMeth] call - - (void) AnnotMeth{}; - ^ - .. _langext-objc-retain-release: Objective-C retaining behavior attributes @@ -1253,8 +1207,7 @@ conventions for ownership of object arguments and return values. However, there are exceptions, and so Clang provides attributes to allow these exceptions to be documented. This are used by ARC and the `static analyzer `_ Some exceptions may be -better described using the :ref:`objc_method_family -` attribute instead. +better described using the ``objc_method_family`` attribute instead. **Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``, ``ns_returns_autoreleased``, ``cf_returns_retained``, and diff --git a/include/clang/Basic/Attr.td b/include/clang/Basic/Attr.td index 9b8160db49..5d66f316c3 100644 --- a/include/clang/Basic/Attr.td +++ b/include/clang/Basic/Attr.td @@ -943,7 +943,7 @@ def ObjCReturnsInnerPointer : InheritableAttr { def ObjCRequiresSuper : InheritableAttr { let Spellings = [GNU<"objc_requires_super">]; let Subjects = SubjectList<[ObjCMethod], ErrorDiag>; - let Documentation = [Undocumented]; + let Documentation = [ObjCRequiresSuperDocs]; } def ObjCRootClass : InheritableAttr { diff --git a/include/clang/Basic/AttrDocs.td b/include/clang/Basic/AttrDocs.td index ca1a37d5a3..5340be42a8 100644 --- a/include/clang/Basic/AttrDocs.td +++ b/include/clang/Basic/AttrDocs.td @@ -266,4 +266,49 @@ use the retaining behavior attributes (``ns_returns_retained``, Query for this feature with ``__has_attribute(objc_method_family)``. }]; +} + +def ObjCRequiresSuperDocs : Documentation { + let Category = DocCatFunction; + let Content = [{ +Some Objective-C classes allow a subclass to override a particular method in a +parent class but expect that the overriding method also calls the overridden +method in the parent class. For these cases, we provide an attribute to +designate that a method requires a "call to ``super``" in the overriding +method in the subclass. + +**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only +be placed at the end of a method declaration: + +.. code-block:: objc + + - (void)foo __attribute__((objc_requires_super)); + +This attribute can only be applied the method declarations within a class, and +not a protocol. Currently this attribute does not enforce any placement of +where the call occurs in the overriding method (such as in the case of +``-dealloc`` where the call must appear at the end). It checks only that it +exists. + +Note that on both OS X and iOS that the Foundation framework provides a +convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this +attribute: + +.. code-block:: objc + + - (void)foo NS_REQUIRES_SUPER; + +This macro is conditionally defined depending on the compiler's support for +this attribute. If the compiler does not support the attribute the macro +expands to nothing. + +Operationally, when a method has this annotation the compiler will warn if the +implementation of an override in a subclass does not call super. For example: + +.. code-block:: objc + + warning: method possibly missing a [super AnnotMeth] call + - (void) AnnotMeth{}; + ^ + }]; } \ No newline at end of file