From 64f7ae3334171168ff803f339d55a179a6e06001 Mon Sep 17 00:00:00 2001
From: Hugo Lima <hugo.lima@openbossa.org>
Date: Thu, 29 Oct 2009 18:26:23 -0200
Subject: Updated documentation of conversion-rule for argument-modification.

Reviewed by Luciano Wolf <luciano.wolf@openbossa.org>
---
 doc/typesystem_arguments.rst            | 33 +++++++++++++++++++++++++++++++++
 doc/typesystem_manipulating_objects.rst |  5 ++++-
 2 files changed, 37 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/typesystem_arguments.rst b/doc/typesystem_arguments.rst
index b3f3e0b59..21e2574a8 100644
--- a/doc/typesystem_arguments.rst
+++ b/doc/typesystem_arguments.rst
@@ -3,6 +3,39 @@
 Modifying Arguments
 -------------------
 
+.. _conversion-rule:
+
+conversion-rule
+^^^^^^^^^^^^^^^
+
+    The conversion-rule node allows you to write customized code to convert
+    the given argument between the target language and C++, and it is a child of the modify-argument node.
+
+    .. code-block:: xml
+
+        <modify-argument ...>
+        <conversion-rule class="target | native">
+            // the code
+        </conversion-rule>
+        </modify-argument>
+
+    This node is typically used in combination with the replace-type and
+    remove-argument nodes. The given code is used instead of the generator's
+    conversion code.
+
+    Writing %N in the code (where N is a number), will insert the name of the
+    nth argument. Alternatively, %in and %out which will be replaced with the
+    name of the conversion's input and output variable, respectively. Note the
+    output variable must be declared explicitly, for example:
+
+    .. code-block:: xml
+
+        <conversion-rule class="native">
+        bool %out = (bool) %in;
+        </conversion-rule>
+
+    .. note:: You can also use the conversion-rule node to specify :ref:`a conversion code which will be used instead of the generator's conversion code everywhere for a given type <conversion-rule-on-types>`.
+
 remove-argument
 ^^^^^^^^^^^^^^^
 
diff --git a/doc/typesystem_manipulating_objects.rst b/doc/typesystem_manipulating_objects.rst
index 34b5f7194..397dfa6ec 100644
--- a/doc/typesystem_manipulating_objects.rst
+++ b/doc/typesystem_manipulating_objects.rst
@@ -98,7 +98,7 @@ add-function
 
     The ``return-type`` attribute defaults to *void*, and the ``access`` to *public*.
 
-.. _conversion-rule:
+.. _conversion-rule-on-types:
 
 conversion-rule
 ^^^^^^^^^^^^^^^
@@ -115,3 +115,6 @@ conversion-rule
         <value-type name="Foo">
             <convertion-rule file="my_converter_implementation.h" />
         </value-type>
+
+    .. 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>`.
+
-- 
cgit v1.2.3