summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorRenato Filho <renato.filho@openbossa.org>2010-05-25 16:15:23 -0300
committerHugo Parente Lima <hugo.pl@gmail.com>2012-03-09 19:10:03 -0300
commitda684da266fe4ca63c7dd7a880988ef08a1fe4ac (patch)
tree0634caa93c93e9031c868442720505494ee5098a /doc
parent2060c23e8d2d80c721dd4eb31a777f4be0fefdfc (diff)
Document about the flag "since".
Reviewer: Luciano Wolf <luciano.wolf@openbossa.org>, Marcelo Lira <marcelo.lira@openbossa.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/typesystem_manipulating_objects.rst15
-rw-r--r--doc/typesystem_specifying_types.rst29
2 files changed, 38 insertions, 6 deletions
diff --git a/doc/typesystem_manipulating_objects.rst b/doc/typesystem_manipulating_objects.rst
index 84a5c1ad..4c812113 100644
--- a/doc/typesystem_manipulating_objects.rst
+++ b/doc/typesystem_manipulating_objects.rst
@@ -15,7 +15,7 @@ inject-code
<value-type>
<inject-code class="native | target | target-declaration"
- position="beginning | end">
+ position="beginning | end" since="...">
// the code
</inject-code>
</value-type>
@@ -33,6 +33,8 @@ inject-code
is inserted at the beginning of the function. If it is set to *end*, the code
is inserted at the end of the function.
+ The ``since`` attribute specify the API version where this code was injected.
+
modify-field
^^^^^^^^^^^^
@@ -66,6 +68,7 @@ modify-function
<object-type>
<modify-function signature="..."
+ since="..."
remove="all | c++"
access="public | private | protected"
rename="..." />
@@ -74,6 +77,8 @@ modify-function
The ``signature`` attribute is a normalized C++ signature, excluding return
values but including potential const declarations.
+ The ``since`` attribute specify the API version when this function was modified.
+
The ``remove``, ``access`` and ``rename`` attributes are *optional* attributes
for added convenience; they serve the same purpose as the deprecated tags :ref:`remove`, :ref:`access` and :ref:`rename`.
@@ -93,11 +98,13 @@ add-function
.. code-block:: xml
<object-type>
- <add-function signature="..." return-type="..." access="public | protected" static="yes | no" />
+ <add-function signature="..." return-type="..." access="public | protected" static="yes | no" since="..."/>
</object-type>
The ``return-type`` attribute defaults to *void*, the ``access`` to *public* and the ``static`` one to *no*.
+ The ``since`` attribute specify the API version when this function was added.
+
.. _conversion-rule-on-types:
conversion-rule
@@ -113,8 +120,10 @@ conversion-rule
.. code-block:: xml
<value-type name="Foo">
- <convertion-rule file="my_converter_implementation.h" />
+ <convertion-rule file="my_converter_implementation.h" since="..."/>
</value-type>
+ The ``since`` attribute specify the API version when this conversion rule became valid.
+
.. note:: You can also use the conversion-rule node to specify :ref:`how the conversion of a single function argument should be done in a function <conversion-rule>`.
diff --git a/doc/typesystem_specifying_types.rst b/doc/typesystem_specifying_types.rst
index cd65c4b5..68b85f5f 100644
--- a/doc/typesystem_specifying_types.rst
+++ b/doc/typesystem_specifying_types.rst
@@ -75,21 +75,25 @@ primitive-type
<typesystem>
<primitive-type name="..."
+ since="..."
target-name="..."
preferred-conversion="yes | no" />
</typesystem>
- The **name** attribute is the name of the primitive in C++, the optimal
+ The **name** attribute is the name of the primitive in C++, the optional,
**target-name** attribute is the name of the primitive type in the target
language. If the later two attributes are not specified their default value
will be the same as the **name** attribute.
+ The *optional* **since** value is used to specify the API version of this type.
+
If the *optional* **preferred-conversion** attribute is set to *no*, it
indicates that this version of the primitive type is not the preferred C++
equivalent of the target language type. For example, in Python both "qint64"
and "long long" become "long" but we should prefer the "qint64" version. For
this reason we mark "long long" with preferred-conversion="no".
+
.. _namespace:
namespace-type
@@ -109,6 +113,8 @@ namespace-type
The **name** attribute is the name of the namespace, e.g., "Qt". The **package**
attribute can be used to override the package of the type system.
+ The *optional* **since** value is used to specify the API version of this type.
+
enum-type
^^^^^^^^^
@@ -120,6 +126,7 @@ enum-type
<typesystem>
<enum-type name="..."
+ since="..."
flags="yes | no"
lower-bound="..."
upper-bound="..."
@@ -139,6 +146,9 @@ enum-type
**extensible** attribute specifies whether the given enum can be extended
with user values (the default is *no*).
+ The *optional* **since** value is used to specify the API version of this type.
+
+
reject-enum-value
^^^^^^^^^^^^^^^^^
@@ -167,7 +177,7 @@ value-type
.. code-block:: xml
<typesystem>
- <value-type name="..."
+ <value-type name="..." since="..."
copyable="yes | no"
hash-function="..."
stream="yes | no" />
@@ -182,6 +192,8 @@ value-type
use externally defined operators, like QDataStream << and >>. If equals to **yes**,
these operators will be called as normal methods within the current class.
+ The *optional* **since** value is used to specify the API version of this type.
+
.. _object-type:
@@ -196,6 +208,7 @@ object-type
<typesystem>
<object-type name="..."
+ since="..."
copyable="yes | no"
hash-function="..."
stream="yes | no" />
@@ -211,6 +224,8 @@ object-type
use externally defined operators, like QDataStream << and >>. If equals to **yes**,
these operators will be called as normal methods within the current class.
+ The *optional* **since** value is used to specify the API version of this type.
+
interface-type
^^^^^^^^^^^^^^
@@ -223,6 +238,7 @@ interface-type
<typesystem>
<interface-type name="..."
+ since="..."
package ="..."
default-superclass ="..." />
</typesystem>
@@ -233,6 +249,8 @@ interface-type
can be used to specify a superclass in the generated target language API, for
the given class.
+ The *optional* **since** value is used to specify the API version of this interface.
+
.. _container-type:
container-type
@@ -245,6 +263,7 @@ container-type
<typesystem>
<container-type name="..."
+ since="..."
type ="..." />
</typesystem>
@@ -253,6 +272,8 @@ container-type
container. It can be: *list*, *string-list*, *linked-list*, *vector*, *stack*,
*queue*, *set*, *map*, *multi-map*, *hash*, *multi-hash* or *pair*.
+ The *optional* **since** value is used to specify the API version of this container.
+
.. _function:
function
@@ -264,9 +285,11 @@ function
.. code-block:: xml
<typesystem>
- <function signature="..." />
+ <function signature="..." since="..."/>
</typesystem>
This tag has some limitations, it doesn't support function modifications, besides you
can't add a function overload using :ref:`add-function` tag to an existent function.
These limitation will be addressed in future versions of ApiExtractor.
+
+ The *optional* **since** value is used to specify the API version of this function.