Skip to content

Fix pointer-to-paramref syntax in docs

FeRD (Frank Dana) requested to merge ferdnyc/glib:pointer-param-docs into main

The documentation for GLib and Gio contains a number of documentation comment blocks where a parameter reference (e.g. @err) is also discussed in its dereferenced pointer form, which is generally annotated as *@err. This inevitably confuses the MarkDown parser, which sees the * as the beginning of an italicized text span.

To avoid this, replace all *@foo with `*foo`, which loses the @-sigil linking it to the @foo parameter, but formats correctly in the rendered documentation. (@foo is automatically formatted like `foo`, so the resulting appearance in the docs is as intended.)

See, for example, the documentation for GLib.set_error:

Complete diff of func.set_error.html as a result of this change

diff -u /tmp/old.html _build_meson/docs/reference/glib/glib-2.0/func.set_error.html
--- /tmp/old.html	2024-12-14 13:35:03.000000000 -0500
+++ _build_meson/docs/reference/glib/glib-2.0/func.set_error.html	2024-12-15 18:45:44.347783211 -0500
@@ -130,8 +130,8 @@
       </h4>
 
       <div class="docblock">
-        <p>Does nothing if <code>err</code> is <code>NULL</code>; if <code>err</code> is non-<code>NULL</code>, then <em><code>err</code>
-must be <code>NULL</code>. A new <code>GError</code> is created and assigned to </em><code>err</code>.</p>
+        <p>Does nothing if <code>err</code> is <code>NULL</code>; if <code>err</code> is non-<code>NULL</code>, then <code>*err</code>
+must be <code>NULL</code>. A new <code>GError</code> is created and assigned to <code>*err</code>.</p>
       </div>
 
       <div class="docblock">

Before (live docs)

image

After (rendered from MR branch)

image

Edited by FeRD (Frank Dana)

Merge request reports

Loading