Initial import of SIP4 for Qt3

1 files changed, 805 insertions, 0 deletions

diff --git a/sphinx/annotations.rst b/sphinx/annotations.rst
new file mode 100644
index 0000000..05ab847
--- /dev/null
+++ b/sphinx/annotations.rst
@@ -0,0 +1,805 @@
+Annotations
+===========
+
+In this section we describe each of the annotations that can be used in
+specification files.
+
+Annotations can either be :ref:`argument annotations <ref-arg-annos>`,
+:ref:`class annotations <ref-class-annos>`, :ref:`mapped type annotations
+<ref-mapped-type-annos>`, :ref:`enum annotations <ref-enum-annos>`,
+:ref:`exception annotations <ref-exception-annos>`, :ref:`function annotations
+<ref-function-annos>`, :ref:`license annotations <ref-license-annos>`,
+:ref:`typedef annotations <ref-typedef-annos>` or :ref:`variable annotations
+<ref-variable-annos>` depending on the context in which they can be used.
+
+Annotations are placed between forward slashes (``/``).  Multiple annotations
+are comma separated within the slashes.
+
+Annotations have a type and, possibly, a value.  The type determines the
+format of the value.  The name of an annotation and its value are separated by
+``=``.
+
+Annotations can have one of the following types:
+
+*boolean*
+    This type of annotation has no value and is implicitly true.
+
+*name*
+    The value is a name that is compatible with a C/C++ identifier.  In some
+    cases the value is optional.
+
+*dotted name*
+    The value is a name that is compatible with an identifier preceded by a
+    Python scope.
+
+*string*
+    The value is a double quoted string.
+
+*API range*
+    The value is the name of an API (defined using the :directive:`%API`
+    directive) separated by a range of version numbers with a colon.
+
+    The range of version numbers is a pair of numbers separated by a hyphen
+    specifying the lower and upper bounds of the range.  A version number is
+    within the range if it is greater or equal to the lower bound and less
+    than the upper bound.  Each bound can be omitted meaning that the range is
+    unbounded in that direction.
+
+    For example::
+
+        # This is part of the PyQt4 API up to but excluding v2.
+        void hex() /API=PyQt4:-2/
+
+        # This is part of the PyQt4 API starting from v2.
+        void hex() /PyName=hex_, API=PyQt4:2-/
+
+The following example shows argument and function annotations::
+
+    void exec(QWidget * /Transfer/) /ReleaseGIL, PyName=call_exec/;
+
+Note that the current version of SIP does not complain about unknown
+annotations, or annotations used out of their correct context.
+
+
+.. _ref-arg-annos:
+
+Argument Annotations
+--------------------
+
+.. argument-annotation:: AllowNone
+
+    This boolean annotation specifies that the value of the corresponding
+    argument (which should be either :stype:`SIP_PYCALLABLE`,
+    :stype:`SIP_PYDICT`, :stype:`SIP_PYLIST`, :stype:`SIP_PYSLICE`,
+    :stype:`SIP_PYTUPLE` or :stype:`SIP_PYTYPE`) may be ``None``.
+
+
+.. argument-annotation:: Array
+
+    This boolean annotation specifies that the corresponding argument refers
+    to an array.
+    
+    The argument should be either a pointer to a wrapped type, a ``char *`` or
+    a ``unsigned char *``.  If the argument is a character array then the
+    annotation also implies the :aanno:`Encoding` annotation with an encoding
+    of ``"None"``.
+
+    There must be a corresponding argument with the :aanno:`ArraySize`
+    annotation specified.  The annotation may only be specified once in a list
+    of arguments.
+
+
+.. argument-annotation:: ArraySize
+
+    This boolean annotation specifies that the corresponding argument (which
+    should be either ``short``, ``unsigned short``, ``int``, ``unsigned``,
+    ``long`` or ``unsigned long``) refers to the size of an array.  There must
+    be a corresponding argument with the :aanno:`Array` annotation specified.
+    The annotation may only be specified once in a list of arguments.
+
+
+.. argument-annotation:: Constrained
+
+    Python will automatically convert between certain compatible types.  For
+    example, if a floating pointer number is expected and an integer supplied,
+    then the integer will be converted appropriately.  This can cause problems
+    when wrapping C or C++ functions with similar signatures.  For example::
+
+        // The wrapper for this function will also accept an integer argument
+        // which Python will automatically convert to a floating point number.
+        void foo(double);
+
+        // The wrapper for this function will never get used.
+        void foo(int);
+
+    This boolean annotation specifies that the corresponding argument (which
+    should be either ``bool``, ``int``, ``float``, ``double``, ``enum`` or a
+    wrapped class) must match the type without any automatic conversions.  In
+    the context of a wrapped class the invocation of any
+    :directive:`%ConvertToTypeCode` is suppressed.
+
+    The following example gets around the above problem::
+
+        // The wrapper for this function will only accept floating point
+        // numbers.
+        void foo(double /Constrained/);
+
+        // The wrapper for this function will be used for anything that Python
+        // can convert to an integer, except for floating point numbers.
+        void foo(int);
+
+
+.. argument-annotation:: DocType
+
+    .. versionadded:: 4.10
+
+    This string annotation specifies the type of the argument as it will appear
+    in any generated docstrings.  It is usually used with arguments of type
+    :stype:`SIP_PYOBJECT` to provide a more specific type.
+
+
+.. argument-annotation:: DocValue
+
+    .. versionadded:: 4.10
+
+    This string annotation specifies the default value of the argument as it
+    will appear in any generated docstrings.
+
+
+.. argument-annotation:: Encoding
+
+    This string annotation specifies that the corresponding argument (which
+    should be either ``char``, ``const char``, ``char *`` or ``const char *``)
+    refers to an encoded character or ``'\0'`` terminated encoded string with
+    the specified encoding.  The encoding can be either ``"ASCII"``,
+    ``"Latin-1"``, ``"UTF-8"`` or ``"None"``.  An encoding of ``"None"`` means
+    that the corresponding argument refers to an unencoded character or string.
+
+    The default encoding is specified by the :directive:`%DefaultEncoding`
+    directive.  If the directive is not specified then ``None`` is used.
+
+    Python v3 will use the ``bytes`` type to represent the argument if the
+    encoding is ``"None"`` and the ``str`` type otherwise.
+
+    Python v2 will use the ``str`` type to represent the argument if the
+    encoding is ``"None"`` and the ``unicode`` type otherwise.
+
+
+.. argument-annotation:: GetWrapper
+
+    This boolean annotation is only ever used in conjunction with handwritten
+    code specified with the :directive:`%MethodCode` directive.  It causes an
+    extra variable to be generated for the corresponding argument which is a
+    pointer to the Python object that wraps the argument.
+
+    See the :directive:`%MethodCode` directive for more detail.
+
+
+.. argument-annotation:: In
+
+    This boolean annotation is used to specify that the corresponding argument
+    (which should be a pointer type) is used to pass a value to the function.
+
+    For pointers to wrapped C structures or C++ class instances, ``char *`` and
+    ``unsigned char *`` then this annotation is assumed unless the :aanno:`Out`
+    annotation is specified.
+
+    For pointers to other types then this annotation must be explicitly
+    specified if required.  The argument will be dereferenced to obtain the
+    actual value.
+
+    Both :aanno:`In` and :aanno:`Out` may be specified for the same argument.
+
+
+.. argument-annotation:: KeepReference
+
+    This boolean annotation is used to specify that a reference to the
+    corresponding argument should be kept to ensure that the object is not
+    garbage collected.  If the method is called again with a new argument then
+    the reference to the previous argument is discarded.  Note that ownership
+    of the argument is not changed.
+
+
+.. argument-annotation:: NoCopy
+
+    .. versionadded:: 4.10.1
+
+    This boolean annotation is used with arguments of virtual methods that are
+    a ``const`` reference to a class.  Normally, if the class defines a copy
+    constructor then a copy of the returned reference is automatically created
+    and wrapped before being passed to a Python reimplementation of the method.
+    The copy will be owned by Python.  This means that the reimplementation may
+    take a reference to the argument without having to make an explicit copy.
+    
+    If the annotation is specified then the copy is not made and the original
+    reference is wrapped instead and will be owned by C++.
+
+
+.. argument-annotation:: Out
+
+    This boolean annotation is used to specify that the corresponding argument
+    (which should be a pointer type) is used by the function to return a value
+    as an element of a tuple.
+
+    For pointers to wrapped C structures or C++ class instances, ``char *`` and
+    ``unsigned char *`` then this annotation must be explicitly specified if
+    required.
+
+    For pointers to other types then this annotation is assumed unless the
+    :aanno:`In` annotation is specified.
+
+    Both :aanno:`In` and :aanno:`Out` may be specified for the same argument.
+
+
+.. argument-annotation:: ResultSize
+
+    This boolean annotation is used with functions or methods that return a
+    ``void *`` or ``const void *``.  It identifies an argument that defines the
+    size of the block of memory whose address is being returned.  This allows
+    the ``sip.voidptr`` object that wraps the address to support the Python
+    buffer protocol and allows the memory to be read and updated when wrapped
+    by the Python ``buffer()`` builtin.
+
+
+.. argument-annotation:: SingleShot
+
+    This boolean annotation is used only with arguments of type
+    :stype:`SIP_RXOBJ_CON` to specify that the signal connected to the slot
+    will only ever be emitted once.  This prevents a certain class of memory
+    leaks.
+
+
+.. argument-annotation:: Transfer
+
+    This boolean annotation is used to specify that ownership of the
+    corresponding argument (which should be a wrapped C structure or C++ class
+    instance) is transferred from Python to C++.  In addition, if the argument
+    is of a class method, then it is associated with the class instance with
+    regard to the cyclic garbage collector.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. argument-annotation:: TransferBack
+
+    This boolean annotation is used to specify that ownership of the
+    corresponding argument (which should be a wrapped C structure or C++ class
+    instance) is transferred back to Python from C++.  In addition, any
+    association of the argument with regard to the cyclic garbage collector
+    with another instance is removed.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. argument-annotation:: TransferThis
+
+    This boolean annotation is only used in C++ constructors or methods.  In
+    the context of a constructor or factory method it specifies that ownership
+    of the instance being created is transferred from Python to C++ if the
+    corresponding argument (which should be a wrapped C structure or C++ class
+    instance) is not ``None``.  In addition, the newly created instance is
+    associated with the argument with regard to the cyclic garbage collector.
+
+    In the context of a non-factory method it specifies that ownership of
+    ``this`` is transferred from Python to C++ if the corresponding argument is
+    not ``None``.  If it is ``None`` then ownership is transferred to Python.
+
+    The annotation may be used more that once, in which case ownership is
+    transferred to last instance that is not ``None``.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. _ref-class-annos:
+
+Class Annotations
+-----------------
+
+.. class-annotation:: Abstract
+
+    This boolean annotation is used to specify that the class has additional
+    pure virtual methods that have not been specified and so it cannot be
+    instantiated or sub-classed from Python.
+
+
+.. class-annotation:: AllowNone
+
+    .. versionadded:: 4.8.2
+
+    Normally when a Python object is converted to a C/C++ instance ``None``
+    is handled automatically before the class's
+    :directive:`%ConvertToTypeCode` is called.  This boolean annotation
+    specifies that the handling of ``None`` will be left to the
+    :directive:`%ConvertToTypeCode`.  The annotation is ignored if the class
+    does not have any :directive:`%ConvertToTypeCode`.
+
+
+.. class-annotation:: API
+
+    .. versionadded:: 4.9
+
+    This API range annotation is used to specify an API and corresponding
+    range of version numbers that the class is enabled for.
+
+    If a class or mapped type has different implementations enabled for
+    different ranges of version numbers then those ranges must not overlap.
+
+    See :ref:`ref-incompat-apis` for more detail.
+
+
+.. class-annotation:: DelayDtor
+
+    This boolean annotation is used to specify that the class's destructor
+    should not be called until the Python interpreter exits.  It would normally
+    only be applied to singleton classes.
+
+    When the Python interpreter exits the order in which any wrapped instances
+    are garbage collected is unpredictable.  However, the underlying C or C++
+    instances may need to be destroyed in a certain order.  If this annotation
+    is specified then when the wrapped instance is garbage collected the C or
+    C++ instance is not destroyed but instead added to a list of delayed
+    instances.  When the interpreter exits then the function
+    :cfunc:`sipDelayedDtors()` is called with the list of delayed instances.
+    :cfunc:`sipDelayedDtors()` can then choose to call (or ignore) the
+    destructors in any desired order.
+
+    The :cfunc:`sipDelayedDtors()` function must be specified using the
+    :directive:`%ModuleCode` directive.
+
+.. cfunction:: void sipDelayedDtors(const sipDelayedDtor *dd_list)
+
+    :param dd_list:
+        the linked list of delayed instances.
+
+.. ctype:: sipDelayedDtor
+
+    This structure describes a particular delayed destructor.
+
+    .. cmember:: const char *dd_name
+
+        This is the name of the class excluding any package or module name.
+
+    .. cmember:: void *dd_ptr
+
+        This is the address of the C or C++ instance to be destroyed.  It's
+        exact type depends on the value of :cmember:`dd_isderived`.
+
+    .. cmember:: int dd_isderived
+
+        This is non-zero if the type of :cmember:`dd_ptr` is actually the
+        generated derived class.  This allows the correct destructor to be
+        called.  See :ref:`ref-derived-classes`.
+
+    .. cmember:: sipDelayedDtor *dd_next
+
+        This is the address of the next entry in the list or zero if this is
+        the last one.
+
+    Note that the above applies only to C and C++ instances that are owned by
+    Python.
+
+
+.. class-annotation:: Deprecated
+
+    This boolean annotation is used to specify that the class is deprecated.
+    It is the equivalent of annotating all the class's constructors, function
+    and methods as being deprecated.
+
+
+.. class-annotation:: External
+
+    This boolean annotation is used to specify that the class is defined in
+    another module.  Declarations of external classes are private to the module
+    in which they appear.
+
+
+.. class-annotation:: Metatype
+
+    This dotted name annotation specifies the name of the Python type object
+    (i.e. the value of the ``tp_name`` field) used as the meta-type used when
+    creating the type object for this C structure or C++ type.
+
+    See the section :ref:`ref-types-metatypes` for more details.
+
+
+.. class-annotation:: NoDefaultCtors
+
+    This boolean annotation is used to suppress the automatic generation of
+    default constructors for the class.
+
+
+.. class-annotation:: PyName
+
+    This name annotation specifies an alternative name for the class being
+    wrapped which is used when it is referred to from Python.  It is required
+    when a class name is the same as a Python keyword.  It may also be used to
+    avoid name clashes with other objects (e.g. enums, exceptions, functions)
+    that have the same name in the same C++ scope.
+
+
+.. class-annotation:: Supertype
+
+    This dotted name annotation specifies the name of the Python type object
+    (i.e. the value of the ``tp_name`` field) used as the super-type used when
+    creating the type object for this C structure or C++ type.
+
+    See the section :ref:`ref-types-metatypes` for more details.
+
+
+.. _ref-mapped-type-annos:
+
+Mapped Type Annotations
+-----------------------
+
+.. mapped-type-annotation:: AllowNone
+
+    Normally when a Python object is converted to a C/C++ instance ``None``
+    is handled automatically before the mapped type's
+    :directive:`%ConvertToTypeCode` is called.  This boolean annotation
+    specifies that the handling of ``None`` will be left to the
+    :directive:`%ConvertToTypeCode`.
+
+
+.. mapped-type-annotation:: API
+
+    .. versionadded:: 4.9
+
+    This API range annotation is used to specify an API and corresponding
+    range of version numbers that the mapped type is enabled for.
+
+    If a class or mapped type has different implementations enabled for
+    different ranges of version numbers then those ranges must not overlap.
+
+    See :ref:`ref-incompat-apis` for more detail.
+
+
+.. mapped-type-annotation:: DocType
+
+    .. versionadded:: 4.10
+
+    This string annotation specifies the name of the type as it will appear in
+    any generated docstrings.
+
+
+.. mapped-type-annotation:: NoRelease
+
+    This boolean annotation is used to specify that the mapped type does not
+    support the :cfunc:`sipReleaseType()` function.  Any
+    :directive:`%ConvertToTypeCode` should not create temporary instances of
+    the mapped type, i.e. it should not return :cmacro:`SIP_TEMPORARY`.
+
+
+.. _ref-enum-annos:
+
+Enum Annotations
+----------------
+
+.. enum-annotation:: PyName
+
+    This name annotation specifies an alternative name for the enum or enum
+    member being wrapped which is used when it is referred to from Python.  It
+    is required when an enum or enum member name is the same as a Python
+    keyword.  It may also be used to avoid name clashes with other objects
+    (e.g. classes, exceptions, functions) that have the same name in the same
+    C++ scope.
+
+
+.. _ref-exception-annos:
+
+Exception Annotations
+---------------------
+
+.. exception-annotation:: Default
+
+    This boolean annotation specifies that the exception being defined will be
+    used as the default exception to be caught if a function or constructor
+    does not have a ``throw`` clause.
+
+.. exception-annotation:: PyName
+
+    This name annotation specifies an alternative name for the exception being
+    defined which is used when it is referred to from Python.  It is required
+    when an exception name is the same as a Python keyword.  It may also be
+    used to avoid name clashes with other objects (e.g. classes, enums,
+    functions) that have the same name.
+
+
+.. _ref-function-annos:
+
+Function Annotations
+--------------------
+
+.. function-annotation:: API
+
+    .. versionadded:: 4.9
+
+    This API range annotation is used to specify an API and corresponding
+    range of version numbers that the function is enabled for.
+
+    See :ref:`ref-incompat-apis` for more detail.
+
+
+.. function-annotation:: AutoGen
+
+    This optional name annotation is used with class methods to specify that
+    the method be automatically included in all sub-classes.  The value is the
+    name of a feature (specified using the :directive:`%Feature` directive)
+    which must be enabled for the method to be generated.
+
+
+.. function-annotation:: Default
+
+    This boolean annotation is only used with C++ constructors.  Sometimes SIP
+    needs to create a class instance.  By default it uses a constructor with no
+    compulsory arguments if one is specified.  (SIP will automatically generate
+    a constructor with no arguments if no constructors are specified.)  This
+    annotation is used to explicitly specify which constructor to use.  Zero is
+    passed as the value of any arguments to the constructor.
+
+
+.. function-annotation:: Deprecated
+
+    This boolean annotation is used to specify that the constructor or function
+    is deprecated.  A deprecation warning is issued whenever the constructor or
+    function is called.
+
+
+.. function-annotation:: DocType
+
+    .. versionadded:: 4.10
+
+    This string annotation specifies the name of the type of the returned value
+    as it will appear in any generated docstrings.  It is usually used with
+    values of type :stype:`SIP_PYOBJECT` to provide a more specific type.
+
+
+.. function-annotation:: Factory
+
+    This boolean annotation specifies that the value returned by the function
+    (which should be a wrapped C structure or C++ class instance) is a newly
+    created instance and is owned by Python.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. function-annotation:: HoldGIL
+
+    This boolean annotation specifies that the Python Global Interpreter Lock
+    (GIL) is not released before the call to the underlying C or C++ function.
+    See :ref:`ref-gil` and the :fanno:`ReleaseGIL` annotation.
+
+
+.. function-annotation:: KeywordArgs
+
+    .. versionadded:: 4.10
+
+    This boolean annotation specifies that the argument parser generated for
+    this function will support passing the parameters using Python's keyword
+    argument syntax.  Keyword arguments cannot be used for functions that have
+    unnamed arguments or use an ellipsis to designate that the function has a
+    variable number of arguments.
+
+
+.. function-annotation:: __len__
+
+    .. versionadded:: 4.10.3
+
+    This boolean annotation specifies that a ``__len__()`` method should be
+    automatically generated that will use the method being annotated to compute
+    the value that the ``__len__()`` method will return.
+
+
+.. function-annotation:: NewThread
+
+    This boolean annotation specifies that the function will create a new
+    thread.
+
+
+.. function-annotation:: NoArgParser
+
+    This boolean annotation is used with methods and global functions to
+    specify that the supplied :directive:`%MethodCode` will handle the parsing
+    of the arguments.
+
+
+.. function-annotation:: NoCopy
+
+    .. versionadded:: 4.10.1
+
+    This boolean annotation is used with methods and global functions that
+    return a ``const`` reference to a class.  Normally, if the class defines a
+    copy constructor then a copy of the returned reference is automatically
+    created and wrapped.  The copy will be owned by Python.
+    
+    If the annotation is specified then the copy is not made and the original
+    reference is wrapped instead and will be owned by C++.
+
+
+.. function-annotation:: NoDerived
+
+    This boolean annotation is only used with C++ constructors.  In many cases
+    SIP generates a derived class for each class being wrapped (see
+    :ref:`ref-derived-classes`).  This derived class contains constructors with
+    the same C++ signatures as the class being wrapped.  Sometimes you may want
+    to define a Python constructor that has no corresponding C++ constructor.
+    This annotation is used to suppress the generation of the constructor in
+    the derived class.
+
+
+.. function-annotation:: NoKeywordArgs
+
+    .. versionadded:: 4.10
+
+    This boolean annotation specifies that the argument parser generated for
+    this function will not support passing the parameters using Python's
+    keyword argument syntax.  In other words, the argument parser will only
+    support only normal positional arguments.  This annotation is useful when
+    the default setting of allowing keyword arguments has been changed via the
+    command line, but you would still like certain functions to only support
+    positional arguments.
+
+
+.. function-annotation:: Numeric
+
+    This boolean annotation specifies that the operator should be interpreted
+    as a numeric operator rather than a sequence operator.  Python uses the
+    ``+`` operator for adding numbers and concatanating sequences, and the
+    ``*`` operator for multiplying numbers and repeating sequences.  SIP tries
+    to work out which is meant by looking at other operators that have been
+    defined for the type.  If it finds either ``-``, ``-=``, ``/``, ``/=``,
+    ``%`` or ``%=`` defined then it assumes that ``+``, ``+=``, ``*`` and
+    ``*=`` should be numeric operators.  Otherwise, if it finds either ``[]``,
+    :meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` defined
+    then it assumes that they should be sequence operators.  This annotation is
+    used to force SIP to treat the operator as numeric.
+
+
+.. function-annotation:: PostHook
+
+    This name annotation is used to specify the name of a Python builtin that
+    is called immediately after the call to the underlying C or C++ function or
+    any handwritten code.  The builtin is not called if an error occurred.  It
+    is primarily used to integrate with debuggers.
+
+
+.. function-annotation:: PreHook
+
+    This name annotation is used to specify the name of a Python builtin that
+    is called immediately after the function's arguments have been successfully
+    parsed and before the call to the underlying C or C++ function or any
+    handwritten code.  It is primarily used to integrate with debuggers.
+
+
+.. function-annotation:: PyName
+
+    This name annotation specifies an alternative name for the function being
+    wrapped which is used when it is referred to from Python.  It is required
+    when a function or method name is the same as a Python keyword.  It may
+    also be used to avoid name clashes with other objects (e.g. classes, enums,
+    exceptions) that have the same name in the same C++ scope.
+
+
+.. function-annotation:: ReleaseGIL
+
+    This boolean annotation specifies that the Python Global Interpreter Lock
+    (GIL) is released before the call to the underlying C or C++ function and
+    reacquired afterwards.  It should be used for functions that might block or
+    take a significant amount of time to execute.  See :ref:`ref-gil` and the
+    :fanno:`HoldGIL` annotation.
+
+
+.. function-annotation:: Transfer
+
+    This boolean annotation specifies that ownership of the value returned by
+    the function (which should be a wrapped C structure or C++ class instance)
+    is transferred to C++.  It is only used in the context of a class
+    constructor or a method.
+
+    In the case of methods returned values (unless they are new references to
+    already wrapped values) are normally owned by C++ anyway.  However, in
+    addition, an association between the returned value and the instance
+    containing the method is created with regard to the cyclic garbage
+    collector.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. function-annotation:: TransferBack
+
+    This boolean annotation specifies that ownership of the value returned by
+    the function (which should be a wrapped C structure or C++ class instance)
+    is transferred back to Python from C++.  Normally returned values (unless
+    they are new references to already wrapped values) are owned by C++.  In
+    addition, any association of the returned value with regard to the cyclic
+    garbage collector with another instance is removed.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. function-annotation:: TransferThis
+
+    This boolean annotation specifies that ownership of ``this`` is transferred
+    from Python to C++.
+
+    See :ref:`ref-object-ownership` for more detail.
+
+
+.. _ref-license-annos:
+
+License Annotations
+-------------------
+
+.. license-annotation:: Licensee
+
+    This optional string annotation specifies the license's licensee.  No
+    restrictions are placed on the contents of the string.
+
+    See the :directive:`%License` directive.
+
+
+.. license-annotation:: Signature
+
+    This optional string annotation specifies the license's signature.  No
+    restrictions are placed on the contents of the string.
+
+    See the :directive:`%License` directive.
+
+
+.. license-annotation:: Timestamp
+
+    This optional string annotation specifies the license's timestamp.  No
+    restrictions are placed on the contents of the string.
+
+    See the :directive:`%License` directive.
+
+
+.. license-annotation:: Type
+
+    This string annotation specifies the license's type.  No restrictions are
+    placed on the contents of the string.
+
+    See the :directive:`%License` directive.
+
+
+.. _ref-typedef-annos:
+
+Typedef Annotations
+-------------------
+
+.. typedef-annotation:: NoTypeName
+
+    This boolean annotation specifies that the definition of the type rather
+    than the name of the type being defined should be used in the generated
+    code.
+
+    Normally a typedef would be defined as follows::
+
+        typedef bool MyBool;
+
+    This would result in ``MyBool`` being used in the generated code.
+
+    Specifying the annotation means that ``bool`` will be used in the generated
+    code instead.
+
+
+.. _ref-variable-annos:
+
+Variable Annotations
+--------------------
+
+.. variable-annotation:: DocType
+
+    .. versionadded:: 4.10
+
+    This string annotation specifies the name of the type of the variable as it
+    will appear in any generated docstrings.  It is usually used with variables
+    of type :stype:`SIP_PYOBJECT` to provide a more specific type.
+
+
+.. variable-annotation:: PyName
+
+    This name annotation specifies an alternative name for the variable being
+    wrapped which is used when it is referred to from Python.  It is required
+    when a variable name is the same as a Python keyword.  It may also be used
+    to avoid name clashes with other objects (e.g. classes, functions) that
+    have the same name in the same C++ scope.