From da684da266fe4ca63c7dd7a880988ef08a1fe4ac Mon Sep 17 00:00:00 2001
From: Renato Filho <renato.filho@openbossa.org>
Date: Tue, 25 May 2010 16:15:23 -0300
Subject: Document about the flag "since".

Reviewer: Luciano Wolf <luciano.wolf@openbossa.org>,
          Marcelo Lira <marcelo.lira@openbossa.org>
---
 doc/typesystem_manipulating_objects.rst | 15 ++++++++++++---
 doc/typesystem_specifying_types.rst     | 29 ++++++++++++++++++++++++++---
 2 files changed, 38 insertions(+), 6 deletions(-)

(limited to 'doc')

diff --git a/doc/typesystem_manipulating_objects.rst b/doc/typesystem_manipulating_objects.rst
index 84a5c1ad7..4c8121135 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 cd65c4b5b..68b85f5f9 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.
-- 
cgit v1.2.3