[gi-docgen/ebassi/argument-annotation: 6/8] Restructure the arguments and return value sections




commit ed5928f56cbac855ae8d9dfcb58b466a796902b5
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Fri May 21 14:53:12 2021 +0100

    Restructure the arguments and return value sections
    
    Reword the generated content:
    
     - expand the "direction" using a proper explanation instead of in, out,
       or in-out
     - refer to argument or return value
     - structure the return value table like the arguments one
     - add style classes to the tables
     - check for array or list independently from the generated link
    
    We also make sure that every callable template follows the same pattern
    for the arguments and return value section.

 gidocgen/gdgenerate.py                     |  9 +++---
 gidocgen/templates/basic/class_method.html | 41 +++++++++++++-----------
 gidocgen/templates/basic/function.html     | 43 +++++++++++++------------
 gidocgen/templates/basic/method.html       | 33 ++++++++++---------
 gidocgen/templates/basic/vfunc.html        | 51 +++++++++++++++++++-----------
 5 files changed, 99 insertions(+), 78 deletions(-)
---
diff --git a/gidocgen/gdgenerate.py b/gidocgen/gdgenerate.py
index cda317a..dc737f1 100644
--- a/gidocgen/gdgenerate.py
+++ b/gidocgen/gdgenerate.py
@@ -40,9 +40,9 @@ RETVAL_TRANSFER_MODES = {
 }
 
 DIRECTION_MODES = {
-    'in': 'in',
-    'inout': 'in-out',
-    'out': 'out',
+    'in': '-',
+    'inout': 'The argument will be modified by the function.',
+    'out': 'The argument will be set by the function.',
 }
 
 SCOPE_MODES = {
@@ -349,7 +349,8 @@ class TemplateArgument:
         self.is_macro = isinstance(call, gir.FunctionMacro)
         self.transfer = argument.transfer or 'none'
         self.transfer_note = ARG_TRANSFER_MODES[argument.transfer or 'none']
-        self.direction = DIRECTION_MODES[argument.direction]
+        self.direction = argument.direction or 'in'
+        self.direction_note = DIRECTION_MODES[argument.direction]
         self.optional = argument.optional
         self.nullable = argument.nullable
         self.scope = SCOPE_MODES[argument.scope or 'none']
diff --git a/gidocgen/templates/basic/class_method.html b/gidocgen/templates/basic/class_method.html
index 222bb18..a26e93f 100644
--- a/gidocgen/templates/basic/class_method.html
+++ b/gidocgen/templates/basic/class_method.html
@@ -99,14 +99,14 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
       </h4>
 
       <div class="docblock">
-        <table>
+        <table class="arguments">
           {% for arg in class_method.arguments %}
           <tr class="arg-name">
             <td><code>{{ arg.name }}</code></td>
             <td>
-            {%- if arg.link -%}
             {%- if arg.is_array -%}An array of&nbsp;{%- endif -%}
             {%- if arg.is_list -%}A list of&nbsp;{%- endif -%}
+            {%- if arg.link -%}
             {{ arg.link|safe }}
             {%- else -%}
             <code>{{ arg.type_cname }}</code>
@@ -115,14 +115,15 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
           </tr>
           <tr class="arg-description">
             <td>&nbsp;</td>
-            <td>{{ arg.description }}</td>
+            <td>{{ arg.description|safe }}</td>
           </tr>
-          {% if arg.direction != "in" %}<tr><td>&nbsp;</td><td>Direction: {{ arg.direction }}</td></tr>{% 
endif %}
-          {% if arg.direction == "in" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>Can be 
<code>NULL</code></td></tr>{% endif %}
-          {% if arg.direction == "out" and arg.optional %}<tr><td>&nbsp;</td><td>Can be 
<code>NULL</code></td></tr>{% endif %}
-          {% if arg.is_array and arg.zero_terminated %}<tr><td>&nbsp;</td><td>The array must be 
<code>NULL</code> terminated</td></tr>{% endif %}
-          {% if arg.is_array and arg.fixed_size > 0 %}<tr><td>&nbsp;</td><td>The array must have {{ 
arg.fixed_size }} elements</td></tr>{% endif %}
-          {% if arg.is_array and arg.len_arg %}<tr><td>&nbsp;</td><td>The length of the array is in the 
<code>{{ arg.len_arg }}</code> argument</td></tr>{% endif %}
+          {% if arg.direction != "in" %}<tr><td>&nbsp;</td><td title="direction: {{ arg.direction}}">{{ 
arg.direction_note }}</td></tr>{% endif %}
+          {% if arg.direction == "in" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>The 
argument can be <code>NULL</code>.</td></tr>{% endif %}
+          {% if arg.direction == "out" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>The 
argument can be set to <code>NULL</code>.</td></tr>{% endif %}
+          {% if arg.optional %}<tr><td>&nbsp;</td><td>The argument can be <code>NULL</code>.</td></tr>{% 
endif %}
+          {% if arg.is_array and arg.zero_terminated %}<tr><td>&nbsp;</td><td>The array must be 
<code>NULL</code>-terminated.</td></tr>{% endif %}
+          {% if arg.is_array and arg.fixed_size > 0 %}<tr><td>&nbsp;</td><td>The array must have {{ 
arg.fixed_size }} elements.</td></tr>{% endif %}
+          {% if arg.is_array and arg.len_arg %}<tr><td>&nbsp;</td><td>The length of the array is specified 
in the <code>{{ arg.len_arg }}</code> argument.</td></tr>{% endif %}
           {% if arg.is_pointer %}<tr><td>&nbsp;</td><td title="transfer: {{ arg.transfer }}">{{ 
arg.transfer_note }}</td></tr>{% endif %}
           {% if arg.string_note %}<tr><td>&nbsp;</td><td>{{ arg.string_note }}</td></tr>{% endif %}
           {% endfor %}
@@ -149,12 +150,13 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
       </h4>
 
       <div class="docblock">
-        <table>
+        <table class="returns">
           <tr class="arg-name">
-            <td colspan="2">Returns:&nbsp;
-            {%- if class_method.return_value.link -%}
+            <td>Returns:</td>
+            <td>
             {%- if class_method.return_value.is_array -%}An array of&nbsp;{%- endif -%}
             {%- if class_method.return_value.is_list -%}A list of&nbsp;{%- endif -%}
+            {%- if class_method.return_value.link -%}
             {{ class_method.return_value.link|safe }}
             {%- else -%}
             <code>{{ class_method.return_value.type_cname }}</code>
@@ -162,14 +164,15 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
             </td>
           </tr>
           <tr class="arg-description">
-            <td colspan="2">{{ class_method.return_value.description }}</td>
+            <td>&nbsp;</td>
+            <td>{{ class_method.return_value.description|safe }}</td>
           </tr>
-          {% if class_method.return_value.is_array and class_method.return_value.zero_terminated 
%}<tr><td>&nbsp;</td><td>The array must be <code>NULL</code> terminated</td></tr>{% endif %}
-          {% if class_method.return_value.is_array and class_method.return_value.fixed_size > 0 
%}<tr><td>&nbsp;</td><td>The array must have {{ class_method.return_value.fixed_size }} elements</td></tr>{% 
endif %}
-          {% if class_method.return_value.is_array and class_method.return_value.len_arg 
%}<tr><td>&nbsp;</td><td>The length of the array is in the <code>{{ class_method.return_value.len_arg 
}}</code> argument</td></tr>{% endif %}
-          {% if class_method.return_value.is_pointer %}<tr><td title="transfer: {{ 
class_method.return_value.transfer }}">{{ class_method.return_value.transfer }}</td></tr>{% endif %}
-          {% if class_method.return_value.is_pointer and class_method.return_value.nullable %}<tr><td>Can be 
<code>NULL</code></td></tr>{% endif %}
-          {% if class_method.return_value.string_note %}<tr><td>{{ class_method.return_value.string_note 
}}</td></tr>{% endif %}
+          {% if class_method.return_value.is_array and class_method.return_value.zero_terminated 
%}<tr><td>&nbsp;</td><td>The array is <code>NULL</code>-terminated.</td></tr>{% endif %}
+          {% if class_method.return_value.is_array and class_method.return_value.fixed_size > 0 
%}<tr><td>&nbsp;</td><td>The array has {{ class_method.return_value.fixed_size }} elements.</td></tr>{% endif 
%}
+          {% if class_method.return_value.is_array and class_method.return_value.len_arg 
%}<tr><td>&nbsp;</td><td>The length of the array is in the <code>{{ class_method.return_value.len_arg 
}}</code> argument.</td></tr>{% endif %}
+          {% if class_method.return_value.is_pointer %}<tr><td>&nbsp;</td><td title="transfer: {{ 
class_method.return_value.transfer }}">{{ class_method.return_value.transfer_note }}</td></tr>{% endif %}
+          {% if class_method.return_value.is_pointer and class_method.return_value.nullable 
%}<tr><td>&nbsp;</td><td>The return value can be <code>NULL</code>.</td></tr>{% endif %}
+          {% if class_method.return_value.string_note %}<tr><td>&nbsp;</td><td>{{ 
class_method.return_value.string_note }}</td></tr>{% endif %}
         </table>
       </div>
     </div>
diff --git a/gidocgen/templates/basic/function.html b/gidocgen/templates/basic/function.html
index 367ae68..5b19b74 100644
--- a/gidocgen/templates/basic/function.html
+++ b/gidocgen/templates/basic/function.html
@@ -106,32 +106,31 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
       </h4>
 
       <div class="docblock">
-        <table>
+        <table class="arguments">
           {% for arg in func.arguments %}
           <tr class="arg-name">
             <td><code>{{ arg.name }}</code></td>
-            {% if not arg.is_macro %}
             <td>
-            {%- if arg.link -%}
             {%- if arg.is_array -%}An array of&nbsp;{%- endif -%}
             {%- if arg.is_list -%}A list of&nbsp;{%- endif -%}
+            {%- if arg.link -%}
             {{ arg.link|safe }}
             {%- else -%}
             <code>{{ arg.type_cname }}</code>
             {%- endif -%}
             </td>
-            {% endif %}
           </tr>
           <tr class="arg-description">
             <td>&nbsp;</td>
-            <td>{{ arg.description }}</td>
+            <td>{{ arg.description|safe }}</td>
           </tr>
-          {% if arg.direction != "in" %}<tr><td>&nbsp;</td><td>Direction: {{ arg.direction }}</td></tr>{% 
endif %}
-          {% if arg.direction == "in" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>Can be 
<code>NULL</code></td></tr>{% endif %}
-          {% if arg.direction == "out" and arg.optional %}<tr><td>&nbsp;</td><td>Can be 
<code>NULL</code></td></tr>{% endif %}
-          {% if arg.is_array and arg.zero_terminated %}<tr><td>&nbsp;</td><td>The array must be 
<code>NULL</code> terminated</td></tr>{% endif %}
-          {% if arg.is_array and arg.fixed_size > 0 %}<tr><td>&nbsp;</td><td>The array must have {{ 
arg.fixed_size }} elements</td></tr>{% endif %}
-          {% if arg.is_array and arg.len_arg %}<tr><td>&nbsp;</td><td>The length of the array is in the 
<code>{{ arg.len_arg }}</code> argument</td></tr>{% endif %}
+          {% if arg.direction != "in" %}<tr><td>&nbsp;</td><td title="direction: {{ arg.direction}}">{{ 
arg.direction_note }}</td></tr>{% endif %}
+          {% if arg.direction == "in" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>The 
argument can be <code>NULL</code>.</td></tr>{% endif %}
+          {% if arg.direction == "out" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>The 
argument can be set to <code>NULL</code>.</td></tr>{% endif %}
+          {% if arg.optional %}<tr><td>&nbsp;</td><td>The argument can be <code>NULL</code>.</td></tr>{% 
endif %}
+          {% if arg.is_array and arg.zero_terminated %}<tr><td>&nbsp;</td><td>The array must be 
<code>NULL</code>-terminated.</td></tr>{% endif %}
+          {% if arg.is_array and arg.fixed_size > 0 %}<tr><td>&nbsp;</td><td>The array must have {{ 
arg.fixed_size }} elements.</td></tr>{% endif %}
+          {% if arg.is_array and arg.len_arg %}<tr><td>&nbsp;</td><td>The length of the array is specified 
in the <code>{{ arg.len_arg }}</code> argument.</td></tr>{% endif %}
           {% if arg.is_pointer %}<tr><td>&nbsp;</td><td title="transfer: {{ arg.transfer }}">{{ 
arg.transfer_note }}</td></tr>{% endif %}
           {% if arg.string_note %}<tr><td>&nbsp;</td><td>{{ arg.string_note }}</td></tr>{% endif %}
           {% endfor %}
@@ -158,12 +157,13 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
       </h4>
 
       <div class="docblock">
-        <table>
+        <table class="returns">
           <tr class="arg-name">
-            <td colspan="2">Returns:&nbsp;
-            {%- if func.return_value.link -%}
+            <td>Returns:</td>
+            <td>
             {%- if func.return_value.is_array -%}An array of&nbsp;{%- endif -%}
             {%- if func.return_value.is_list -%}A list of&nbsp;{%- endif -%}
+            {%- if func.return_value.link -%}
             {{ func.return_value.link|safe }}
             {%- else -%}
             <code>{{ func.return_value.type_cname }}</code>
@@ -171,14 +171,15 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
             </td>
           </tr>
           <tr class="arg-description">
-            <td colspan="2">{{ func.return_value.description }}</td>
+            <td>&nbsp;</td>
+            <td>{{ func.return_value.description|safe }}</td>
           </tr>
-          {% if func.return_value.is_array and func.return_value.zero_terminated 
%}<tr><td>&nbsp;</td><td>The array must be <code>NULL</code> terminated</td></tr>{% endif %}
-          {% if func.return_value.is_array and func.return_value.fixed_size > 0 %}<tr><td>&nbsp;</td><td>The 
array must have {{ func.return_value.fixed_size }} elements</td></tr>{% endif %}
-          {% if func.return_value.is_array and func.return_value.len_arg %}<tr><td>&nbsp;</td><td>The length 
of the array is in the <code>{{ func.return_value.len_arg }}</code> argument</td></tr>{% endif %}
-          {% if func.return_value.is_pointer %}<tr><td title="transfer: {{ func.return_value.transfer }}">{{ 
func.return_value.transfer_note }}</td></tr>{% endif %}
-          {% if func.return_value.is_pointer and func.return_value.nullable %}<tr><td>Can be 
<code>NULL</code></td></tr>{% endif %}
-          {% if func.return_value.string_note %}<tr><td>{{ func.return_value.string_note }}</td></tr>{% 
endif %}
+          {% if func.return_value.is_array and func.return_value.zero_terminated 
%}<tr><td>&nbsp;</td><td>The array is <code>NULL</code>-terminated.</td></tr>{% endif %}
+          {% if func.return_value.is_array and func.return_value.fixed_size > 0 %}<tr><td>&nbsp;</td><td>The 
array has {{ func.return_value.fixed_size }} elements.</td></tr>{% endif %}
+          {% if func.return_value.is_array and func.return_value.len_arg %}<tr><td>&nbsp;</td><td>The length 
of the array is in the <code>{{ func.return_value.len_arg }}</code> argument.</td></tr>{% endif %}
+          {% if func.return_value.is_pointer %}<tr><td>&nbsp;</td><td title="transfer: {{ 
func.return_value.transfer }}">{{ func.return_value.transfer_note }}</td></tr>{% endif %}
+          {% if func.return_value.is_pointer and func.return_value.nullable %}<tr><td>&nbsp;</td><td>The 
return value can be <code>NULL</code>.</td></tr>{% endif %}
+          {% if func.return_value.string_note %}<tr><td>&nbsp;</td><td>{{ func.return_value.string_note 
}}</td></tr>{% endif %}
         </table>
       </div>
     </div>
diff --git a/gidocgen/templates/basic/method.html b/gidocgen/templates/basic/method.html
index ba6a9c6..49d1fe1 100644
--- a/gidocgen/templates/basic/method.html
+++ b/gidocgen/templates/basic/method.html
@@ -101,14 +101,14 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
       </h4>
 
       <div class="docblock">
-        <table>
+        <table class="arguments">
           {% for arg in method.arguments %}
           <tr class="arg-name">
             <td><code>{{ arg.name }}</code></td>
             <td>
-            {%- if arg.link -%}
             {%- if arg.is_array -%}An array of&nbsp;{%- endif -%}
             {%- if arg.is_list -%}A list of&nbsp;{%- endif -%}
+            {%- if arg.link -%}
             {{ arg.link|safe }}
             {%- else -%}
             <code>{{ arg.type_cname }}</code>
@@ -119,12 +119,13 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
             <td>&nbsp;</td>
             <td>{{ arg.description|safe }}</td>
           </tr>
-          {% if arg.direction != "in" %}<tr><td>&nbsp;</td><td>Direction: {{ arg.direction }}</td>.</tr>{% 
endif %}
-          {% if arg.direction == "in" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>Can be 
<code>NULL</code>.</td></tr>{% endif %}
-          {% if arg.direction == "out" and arg.optional %}<tr><td>&nbsp;</td><td>Can be 
<code>NULL</code>.</td></tr>{% endif %}
+          {% if arg.direction != "in" %}<tr><td>&nbsp;</td><td title="direction: {{ arg.direction}}">{{ 
arg.direction_note }}</td></tr>{% endif %}
+          {% if arg.direction == "in" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>The 
argument can be <code>NULL</code>.</td></tr>{% endif %}
+          {% if arg.direction == "out" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>The 
argument can be set to <code>NULL</code>.</td></tr>{% endif %}
+          {% if arg.optional %}<tr><td>&nbsp;</td><td>The argument can be <code>NULL</code>.</td></tr>{% 
endif %}
           {% if arg.is_array and arg.zero_terminated %}<tr><td>&nbsp;</td><td>The array must be 
<code>NULL</code>-terminated.</td></tr>{% endif %}
           {% if arg.is_array and arg.fixed_size > 0 %}<tr><td>&nbsp;</td><td>The array must have {{ 
arg.fixed_size }} elements.</td></tr>{% endif %}
-          {% if arg.is_array and arg.len_arg %}<tr><td>&nbsp;</td><td>The length of the array is in the 
<code>{{ arg.len_arg }}</code> argument.</td></tr>{% endif %}
+          {% if arg.is_array and arg.len_arg %}<tr><td>&nbsp;</td><td>The length of the array is specified 
in the <code>{{ arg.len_arg }}</code> argument.</td></tr>{% endif %}
           {% if arg.is_pointer %}<tr><td>&nbsp;</td><td title="transfer: {{ arg.transfer }}">{{ 
arg.transfer_note }}</td></tr>{% endif %}
           {% if arg.string_note %}<tr><td>&nbsp;</td><td>{{ arg.string_note }}</td></tr>{% endif %}
           {% endfor %}
@@ -151,12 +152,13 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
       </h4>
 
       <div class="docblock">
-        <table>
+        <table class="returns">
           <tr class="arg-name">
-            <td colspan="2">Returns:&nbsp;
-            {%- if method.return_value.link -%}
+            <td>Returns:</td>
+            <td>
             {%- if method.return_value.is_array -%}An array of&nbsp;{%- endif -%}
             {%- if method.return_value.is_list -%}A list of&nbsp;{%- endif -%}
+            {%- if method.return_value.link -%}
             {{ method.return_value.link|safe }}
             {%- else -%}
             <code>{{ method.return_value.type_cname }}</code>
@@ -164,14 +166,15 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
             </td>
           </tr>
           <tr class="arg-description">
-            <td colspan="2">{{ method.return_value.description|safe }}</td>
+            <td>&nbsp;</td>
+            <td>{{ method.return_value.description|safe }}</td>
           </tr>
-          {% if method.return_value.is_array and method.return_value.zero_terminated 
%}<tr><td>&nbsp;</td><td>The array must be <code>NULL</code>-terminated.</td></tr>{% endif %}
-          {% if method.return_value.is_array and method.return_value.fixed_size > 0 
%}<tr><td>&nbsp;</td><td>The array must have {{ method.return_value.fixed_size }} elements.</td></tr>{% endif 
%}
+          {% if method.return_value.is_array and method.return_value.zero_terminated 
%}<tr><td>&nbsp;</td><td>The array is <code>NULL</code>-terminated.</td></tr>{% endif %}
+          {% if method.return_value.is_array and method.return_value.fixed_size > 0 
%}<tr><td>&nbsp;</td><td>The array has {{ method.return_value.fixed_size }} elements.</td></tr>{% endif %}
           {% if method.return_value.is_array and method.return_value.len_arg %}<tr><td>&nbsp;</td><td>The 
length of the array is in the <code>{{ method.return_value.len_arg }}</code> argument.</td></tr>{% endif %}
-          {% if method.return_value.is_pointer %}<tr><td title="transfer: {{ method.return_value.transfer 
}}">{{ method.return_value.transfer_note }}</td></tr>{% endif %}
-          {% if method.return_value.is_pointer and method.return_value.nullable %}<tr><td>Can be 
<code>NULL</code>.</td></tr>{% endif %}
-          {% if method.return_value.string_note %}<tr><td>{{ method.return_value.string_note }}</td></tr>{% 
endif %}
+          {% if method.return_value.is_pointer %}<tr><td>&nbsp;</td><td title="transfer: {{ 
method.return_value.transfer }}">{{ method.return_value.transfer_note }}</td></tr>{% endif %}
+          {% if method.return_value.is_pointer and method.return_value.nullable %}<tr><td>&nbsp;</td><td>The 
return value can be <code>NULL</code>.</td></tr>{% endif %}
+          {% if method.return_value.string_note %}<tr><td>&nbsp;</td><td>{{ method.return_value.string_note 
}}</td></tr>{% endif %}
         </table>
       </div>
     </div>
diff --git a/gidocgen/templates/basic/vfunc.html b/gidocgen/templates/basic/vfunc.html
index c66b668..ef48af9 100644
--- a/gidocgen/templates/basic/vfunc.html
+++ b/gidocgen/templates/basic/vfunc.html
@@ -101,14 +101,14 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
       </h4>
 
       <div class="docblock">
-        <table>
+        <table class="arguments">
           {% for arg in vfunc.arguments %}
           <tr class="arg-name">
             <td><code>{{ arg.name }}</code></td>
             <td>
-            {%- if arg.link -%}
             {%- if arg.is_array -%}An array of&nbsp;{%- endif -%}
             {%- if arg.is_list -%}A list of&nbsp;{%- endif -%}
+            {%- if arg.link -%}
             {{ arg.link|safe }}
             {%- else -%}
             <code>{{ arg.type_cname }}</code>
@@ -117,17 +117,28 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
           </tr>
           <tr class="arg-description">
             <td>&nbsp;</td>
-            <td>{{ arg.description }}</td>
+            <td>{{ arg.description|safe }}</td>
           </tr>
-          {% if arg.direction != "in" %}<tr><td>&nbsp;</td><td>Direction: {{ arg.direction }}</td></tr>{% 
endif %}
-          {% if arg.direction == "in" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>Can be 
<code>NULL</code></td></tr>{% endif %}
-          {% if arg.direction == "out" and arg.optional %}<tr><td>&nbsp;</td><td>Can be 
<code>NULL</code></td></tr>{% endif %}
-          {% if arg.is_array and arg.zero_terminated %}<tr><td>&nbsp;</td><td>The array must be 
<code>NULL</code> terminated</td></tr>{% endif %}
-          {% if arg.is_array and arg.fixed_size > 0 %}<tr><td>&nbsp;</td><td>The array must have {{ 
arg.fixed_size }} elements</td></tr>{% endif %}
-          {% if arg.is_array and arg.len_arg %}<tr><td>&nbsp;</td><td>The length of the array is in the 
<code>{{ arg.len_arg }}</code> argument</td></tr>{% endif %}
+          {% if arg.direction != "in" %}<tr><td>&nbsp;</td><td title="direction: {{ arg.direction}}">{{ 
arg.direction_note }}</td></tr>{% endif %}
+          {% if arg.direction == "in" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>The 
argument can be <code>NULL</code>.</td></tr>{% endif %}
+          {% if arg.direction == "out" and arg.is_pointer and arg.nullable %}<tr><td>&nbsp;</td><td>The 
argument can be set to <code>NULL</code>.</td></tr>{% endif %}
+          {% if arg.optional %}<tr><td>&nbsp;</td><td>The argument can be <code>NULL</code>.</td></tr>{% 
endif %}
+          {% if arg.is_array and arg.zero_terminated %}<tr><td>&nbsp;</td><td>The array must be 
<code>NULL</code>-terminated.</td></tr>{% endif %}
+          {% if arg.is_array and arg.fixed_size > 0 %}<tr><td>&nbsp;</td><td>The array must have {{ 
arg.fixed_size }} elements.</td></tr>{% endif %}
+          {% if arg.is_array and arg.len_arg %}<tr><td>&nbsp;</td><td>The length of the array is specified 
in the <code>{{ arg.len_arg }}</code> argument.</td></tr>{% endif %}
           {% if arg.is_pointer %}<tr><td>&nbsp;</td><td title="transfer: {{ arg.transfer }}">{{ 
arg.transfer_note }}</td></tr>{% endif %}
           {% if arg.string_note %}<tr><td>&nbsp;</td><td>{{ arg.string_note }}</td></tr>{% endif %}
           {% endfor %}
+          {% if vfunc.throws %}
+          <tr class="arg-name">
+            <td><code>error</code></td>
+            <td><code>GError **</code></td>
+          </tr>
+          <tr class="arg-description">
+            <td>&nbsp;</td>
+            <td>The return location for a <code>GError*</code>, or <code>NULL</code>.</td>
+          </tr>
+          {% endif %}
         </table>
       </div>
     </div>
@@ -141,12 +152,13 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
       </h4>
 
       <div class="docblock">
-        <table>
+        <table class="returns">
           <tr class="arg-name">
-            <td colspan="2">Returns:&nbsp;
-            {%- if vfunc.return_value.link -%}
+            <td>Returns:</td>
+            <td>
             {%- if vfunc.return_value.is_array -%}An array of&nbsp;{%- endif -%}
             {%- if vfunc.return_value.is_list -%}A list of&nbsp;{%- endif -%}
+            {%- if vfunc.return_value.link -%}
             {{ vfunc.return_value.link|safe }}
             {%- else -%}
             <code>{{ vfunc.return_value.type_cname }}</code>
@@ -154,14 +166,15 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
             </td>
           </tr>
           <tr class="arg-description">
-            <td colspan="2">{{ vfunc.return_value.description }}</td>
+            <td>&nbsp;</td>
+            <td>{{ vfunc.return_value.description|safe }}</td>
           </tr>
-          {% if vfunc.return_value.is_array and vfunc.return_value.zero_terminated 
%}<tr><td>&nbsp;</td><td>The array must be <code>NULL</code> terminated</td></tr>{% endif %}
-          {% if vfunc.return_value.is_array and vfunc.return_value.fixed_size > 0 
%}<tr><td>&nbsp;</td><td>The array must have {{ vfunc.return_value.fixed_size }} elements</td></tr>{% endif %}
-          {% if vfunc.return_value.is_array and vfunc.return_value.len_arg %}<tr><td>&nbsp;</td><td>The 
length of the array is in the <code>{{ vfunc.return_value.len_arg }}</code> argument</td></tr>{% endif %}
-          {% if vfunc.return_value.is_pointer %}<tr><td title="transfer: {{ vfunc.return_value.transfer 
}}">{{ vfunc.return_value.transfer_note }}</td></tr>{% endif %}
-          {% if vfunc.return_value.is_pointer and vfunc.return_value.nullable %}<tr><td>Can be 
<code>NULL</code></td></tr>{% endif %}
-          {% if vfunc.return_value.string_note %}<tr><td>{{ vfunc.return_value.string_note }}</td></tr>{% 
endif %}
+          {% if vfunc.return_value.is_array and vfunc.return_value.zero_terminated 
%}<tr><td>&nbsp;</td><td>The array is <code>NULL</code>-terminated.</td></tr>{% endif %}
+          {% if vfunc.return_value.is_array and vfunc.return_value.fixed_size > 0 
%}<tr><td>&nbsp;</td><td>The array has {{ vfunc.return_value.fixed_size }} elements.</td></tr>{% endif %}
+          {% if vfunc.return_value.is_array and vfunc.return_value.len_arg %}<tr><td>&nbsp;</td><td>The 
length of the array is in the <code>{{ vfunc.return_value.len_arg }}</code> argument.</td></tr>{% endif %}
+          {% if vfunc.return_value.is_pointer %}<tr><td>&nbsp;</td><td title="transfer: {{ 
vfunc.return_value.transfer }}">{{ vfunc.return_value.transfer_note }}</td></tr>{% endif %}
+          {% if vfunc.return_value.is_pointer and vfunc.return_value.nullable %}<tr><td>&nbsp;</td><td>The 
return value can be <code>NULL</code>.</td></tr>{% endif %}
+          {% if vfunc.return_value.string_note %}<tr><td>&nbsp;</td><td>{{ vfunc.return_value.string_note 
}}</td></tr>{% endif %}
         </table>
       </div>
     </div>


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]