[gi-docgen] template: Clarify the GError handling
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gi-docgen] template: Clarify the GError handling
- Date: Fri, 26 Aug 2022 13:44:39 +0000 (UTC)
commit 97366d4e0eaa95314c7b4d900acce56a4578b108
Author: Emmanuele Bassi <ebassi gnome org>
Date: Fri Aug 26 14:42:52 2022 +0100
template: Clarify the GError handling
As it turns out, there are people that do not know how GError works.
Let's make it easier for everybody, and add a link to the rules, as well
as include the fact that you can either pass NULL *or* pass a return
location initialized to NULL.
gidocgen/templates/basic/class_method.html | 7 ++++---
gidocgen/templates/basic/ctor.html | 7 ++++---
gidocgen/templates/basic/function.html | 7 ++++---
gidocgen/templates/basic/method.html | 7 ++++---
gidocgen/templates/basic/signal.html | 10 ++++++++--
gidocgen/templates/basic/type_func.html | 11 ++++++-----
gidocgen/templates/basic/vfunc.html | 7 ++++---
7 files changed, 34 insertions(+), 22 deletions(-)
---
diff --git a/gidocgen/templates/basic/class_method.html b/gidocgen/templates/basic/class_method.html
index 436a321..8cfb7f4 100644
--- a/gidocgen/templates/basic/class_method.html
+++ b/gidocgen/templates/basic/class_method.html
@@ -128,11 +128,12 @@
<dt class="arg-name"><code>error</code></dt>
<dd class="arg-description">
<p><em>Type:</em> <a href="javascript:void(0)" data-namespace="GLib"
data-link="struct.Error.html" class="external"><code>GError **</code></a></p>
- <p>The return location for an error.</p>
+ <p>The return location for <a
href="https://docs.gtk.org/glib/error-reporting.html#rules-for-use-of-gerror";>a recoverable error</a>.</p>
<table>
<tr><td>The argument can be <code>NULL</code>.</td></tr>
- <tr><td>The argument will be set to <code>NULL</code> by the function if there are no
errors.</td></tr>
- <tr><td>In case of error, the argument will be set and the caller will take ownership of the
data, and be responsible for freeing it.</td></tr>
+ <tr><td>If the return location is not <code>NULL</code>, then you must initialize it to a
<code>NULL</code> <code>GError*</code>.</td></tr>
+ <tr><td>The argument will left initialized to <code>NULL</code> by the class method if there
are no errors.</td></tr>
+ <tr><td>In case of error, the argument will be set to a newly allocated <code>GError</code>;
the caller will take ownership of the data, and be responsible for freeing it.</td></tr>
</table>
</dd>
{% endif %}
diff --git a/gidocgen/templates/basic/ctor.html b/gidocgen/templates/basic/ctor.html
index bc06bc6..fe1aadd 100644
--- a/gidocgen/templates/basic/ctor.html
+++ b/gidocgen/templates/basic/ctor.html
@@ -130,11 +130,12 @@
<dt class="arg-name"><code>error</code></dt>
<dd class="arg-description">
<p><em>Type:</em> <a href="javascript:void(0)" data-namespace="GLib"
data-link="struct.Error.html" class="external"><code>GError **</code></a></p>
- <p>The return location for an error.</p>
+ <p>The return location for <a
href="https://docs.gtk.org/glib/error-reporting.html#rules-for-use-of-gerror";>a recoverable error</a>.</p>
<table>
<tr><td>The argument can be <code>NULL</code>.</td></tr>
- <tr><td>The argument will be set to <code>NULL</code> by the function if there are no
errors.</td></tr>
- <tr><td>In case of error, the argument will be set and the caller will take ownership of the
data, and be responsible for freeing it.</td></tr>
+ <tr><td>If the return location is not <code>NULL</code>, then you must initialize it to a
<code>NULL</code> <code>GError*</code>.</td></tr>
+ <tr><td>The argument will left initialized to <code>NULL</code> by the constructor if there
are no errors.</td></tr>
+ <tr><td>In case of error, the argument will be set to a newly allocated <code>GError</code>;
the caller will take ownership of the data, and be responsible for freeing it.</td></tr>
</table>
</dd>
{% endif %}
diff --git a/gidocgen/templates/basic/function.html b/gidocgen/templates/basic/function.html
index 3bfdc0e..57083c0 100644
--- a/gidocgen/templates/basic/function.html
+++ b/gidocgen/templates/basic/function.html
@@ -141,11 +141,12 @@
<dt class="arg-name"><code>error</code></dt>
<dd class="arg-description">
<p><em>Type:</em> <a href="javascript:void(0)" data-namespace="GLib"
data-link="struct.Error.html" class="external"><code>GError **</code></a></p>
- <p>The return location for an error.</p>
+ <p>The return location for <a
href="https://docs.gtk.org/glib/error-reporting.html#rules-for-use-of-gerror";>a recoverable error</a>.</p>
<table>
<tr><td>The argument can be <code>NULL</code>.</td></tr>
- <tr><td>The argument will be set to <code>NULL</code> by the function if there are no
errors.</td></tr>
- <tr><td>In case of error, the argument will be set and the caller will take ownership of the
data, and be responsible for freeing it.</td></tr>
+ <tr><td>If the return location is not <code>NULL</code>, then you must initialize it to a
<code>NULL</code> <code>GError*</code>.</td></tr>
+ <tr><td>The argument will left initialized to <code>NULL</code> by the function if there are
no errors.</td></tr>
+ <tr><td>In case of error, the argument will be set to a newly allocated <code>GError</code>;
the caller will take ownership of the data, and be responsible for freeing it.</td></tr>
</table>
</dd>
{% endif %}
diff --git a/gidocgen/templates/basic/method.html b/gidocgen/templates/basic/method.html
index cbd1894..a80211b 100644
--- a/gidocgen/templates/basic/method.html
+++ b/gidocgen/templates/basic/method.html
@@ -136,11 +136,12 @@
<dt class="arg-name"><code>error</code></dt>
<dd class="arg-description">
<p><em>Type:</em> <a href="javascript:void(0)" data-namespace="GLib"
data-link="struct.Error.html" class="external"><code>GError **</code></a></p>
- <p>The return location for an error.</p>
+ <p>The return location for <a
href="https://docs.gtk.org/glib/error-reporting.html#rules-for-use-of-gerror";>a recoverable error</a>.</p>
<table>
<tr><td>The argument can be <code>NULL</code>.</td></tr>
- <tr><td>The argument will be set to <code>NULL</code> by the function if there are no
errors.</td></tr>
- <tr><td>In case of error, the argument will be set and the caller will take ownership of the
data, and be responsible for freeing it.</td></tr>
+ <tr><td>If the return location is not <code>NULL</code>, then you must initialize it to a
<code>NULL</code> <code>GError*</code>.</td></tr>
+ <tr><td>The argument will left initialized to <code>NULL</code> by the method if there are no
errors.</td></tr>
+ <tr><td>In case of error, the argument will be set to a newly allocated <code>GError</code>;
the caller will take ownership of the data, and be responsible for freeing it.</td></tr>
</table>
</dd>
{% endif %}
diff --git a/gidocgen/templates/basic/signal.html b/gidocgen/templates/basic/signal.html
index b8eb801..3957a6a 100644
--- a/gidocgen/templates/basic/signal.html
+++ b/gidocgen/templates/basic/signal.html
@@ -137,10 +137,16 @@
<dt class="arg-name"><code>error</code></dt>
<dd class="arg-description">
<p><em>Type:</em> <code>GError **</code></p>
- <p>The return location for a <code>GError*</code>, or <code>NULL</code>.</p>
+ <p>The return location for <a
href="https://docs.gtk.org/glib/error-reporting.html#rules-for-use-of-gerror";>a recoverable error</a>.</p>
+ <table>
+ <tr><td>The argument can be <code>NULL</code>.</td></tr>
+ <tr><td>If the return location is not <code>NULL</code>, then you must initialize it to a
<code>NULL</code> <code>GError*</code>.</td></tr>
+ <tr><td>The argument will left initialized to <code>NULL</code> by the signal handler if there
are no errors.</td></tr>
+ <tr><td>In case of error, the argument will be set to a newly allocated <code>GError</code>;
the caller will take ownership of the data, and be responsible for freeing it.</td></tr>
+ </table>
</dd>
{% endif %}
- </table>
+ </dl>
</div>
</div>
{% endif %}
diff --git a/gidocgen/templates/basic/type_func.html b/gidocgen/templates/basic/type_func.html
index dc57c9e..2984432 100644
--- a/gidocgen/templates/basic/type_func.html
+++ b/gidocgen/templates/basic/type_func.html
@@ -127,15 +127,16 @@
<dt class="arg-name"><code>error</code></dt>
<dd class="arg-description">
<p><em>Type:</em> <a href="javascript:void(0)" data-namespace="GLib"
data-link="struct.Error.html" class="external"><code>GError **</code></a></p>
- <p>The return location for an error.</p>
+ <p>The return location for <a
href="https://docs.gtk.org/glib/error-reporting.html#rules-for-use-of-gerror";>a recoverable error</a>.</p>
<table>
<tr><td>The argument can be <code>NULL</code>.</td></tr>
- <tr><td>The argument will be set to <code>NULL</code> by the function if there are no
errors.</td></tr>
- <tr><td>In case of error, the argument will be set and the caller will take ownership of the
data, and be responsible for freeing it.</td></tr>
+ <tr><td>If the return location is not <code>NULL</code>, then you must initialize it to a
<code>NULL</code> <code>GError*</code>.</td></tr>
+ <tr><td>The argument will left initialized to <code>NULL</code> by the function if there are
no errors.</td></tr>
+ <tr><td>In case of error, the argument will be set to a newly allocated <code>GError</code>;
the caller will take ownership of the data, and be responsible for freeing it.</td></tr>
</table>
- </tr>
+ </dd>
{% endif %}
- </table>
+ </dl>
</div>
</div>
{% endif %}
diff --git a/gidocgen/templates/basic/vfunc.html b/gidocgen/templates/basic/vfunc.html
index 8b8c30d..9b9b998 100644
--- a/gidocgen/templates/basic/vfunc.html
+++ b/gidocgen/templates/basic/vfunc.html
@@ -127,11 +127,12 @@
<dt class="arg-name"><code>error</code></dt>
<dd class="arg-description">
<p><em>Type:</em> <a href="javascript:void(0)" data-namespace="GLib"
data-link="struct.Error.html" class="external"><code>GError **</code></a></p>
- <p>The return location for an error.</p>
+ <p>The return location for <a
href="https://docs.gtk.org/glib/error-reporting.html#rules-for-use-of-gerror";>a recoverable error</a>.</p>
<table>
<tr><td>The argument can be <code>NULL</code>.</td></tr>
- <tr><td>The argument will be set to <code>NULL</code> by the function if there are no
errors.</td></tr>
- <tr><td>In case of error, the argument will be set and the caller will take ownership of the
data, and be responsible for freeing it.</td></tr>
+ <tr><td>If the return location is not <code>NULL</code>, then you must initialize it to a
<code>NULL</code> <code>GError*</code>.</td></tr>
+ <tr><td>The argument will left initialized to <code>NULL</code> by the virtual function if
there are no errors.</td></tr>
+ <tr><td>In case of error, the argument will be set to a newly allocated <code>GError</code>;
the caller will take ownership of the data, and be responsible for freeing it.</td></tr>
</table>
</dd>
{% endif %}
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
