doc: Document function pointer source code style

as implemented in 1356f78ea93395c107cbc75dc923e29a0efccd8a

diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml
index 877fcedbb3a31e68387a33a6e0a6b9fc77f3c0b1..7777bf519958bdf705ffe90ebf3bc4f1c92320e3 100644 (file)
--- a/doc/src/sgml/sources.sgml
+++ b/doc/src/sgml/sources.sgml
@@ -964,5 +964,23 @@ handle_sighup(SIGNAL_ARGS)
     </para>
    </simplesect>
 
+   <simplesect>
+    <title>Calling Function Pointers</title>
+
+    <para>
+     For clarity, it is preferred to explicitly dereference a function pointer
+     when calling the pointed-to function if the pointer is a simple variable,
+     for example:
+<programlisting>
+(*emit_log_hook) (edata);
+</programlisting>
+     (even though <literal>emit_log_hook(edata)</literal> would also work).
+     When the function pointer is part of a structure, then the extra
+     punctuation can and usually should be omitted, for example:
+<programlisting>
+paramInfo->paramFetch(paramInfo, paramId);
+</programlisting>
+    </para>
+   </simplesect>
   </sect1>
  </chapter>