From cacb77e4f2f3d0f94a3c3020f1eb59e6f80929bf Mon Sep 17 00:00:00 2001
From: heck <heck@pep.foundation>
Date: Wed, 21 Jun 2023 20:49:18 +0200
Subject: [PATCH] ig-c99: implement method documentation

---
 lm-c99/ig-c99.ysl2 | 146 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 144 insertions(+), 2 deletions(-)

diff --git a/lm-c99/ig-c99.ysl2 b/lm-c99/ig-c99.ysl2
index 6b7b7b9..2523fc5 100644
--- a/lm-c99/ig-c99.ysl2
+++ b/lm-c99/ig-c99.ysl2
@@ -337,10 +337,152 @@ tstylesheet {
         ||
     }
 
+    def "func:c99_normalize_docstring" {
+        param "docstring";
+        result call "c99_normalize_docstring" with "docstring", "$docstring";
+    }
+    function "c99_normalize_docstring" {
+        param "docstring";
+        for "str:split($docstring, '\n')" {
+            const "doc_line", "normalize-space(.)";
+            if "string-length($doc_line) > 0" {
+               | «$doc_line»
+            }
+        }
+    }
+
     template "method" {
-        call "method"
-            with "idl_method_name", "@name";
+        const "cont", "'@brief Like send_ping_to_unknown_pEp_identiti\nes_in_incoming_message,\n for outgoing messages. Rationale: an identity may be known to use pEp even if we do not know anything about it, thanks to media keys. This is useful when composing a message: we might be able to receive a Pong, and therefore a recipient key,even before sending; this is a way to improve the outgoing message rating.'";
+        call "method_doc" with "idl_method_name", "@name";
+        call "method" with "idl_method_name", "@name";
+        |
+    }
+
+
+    // DOC METHOD
+    // ----------
+
+    function "method_doc" {
+        param "idl_method_name";
+        | /*
+        > «func:c99_method_doc_title($idl_method_name)»
+        > «func:c99_method_doc_brief($idl_method_name)»
+        > «func:c99_method_doc_params($idl_method_name)»
+        > «func:c99_method_doc_throws($idl_method_name)»
+        > «func:c99_method_doc_note($idl_method_name)»
+        |
+        | */
+    }
+
+
+    def "func:c99_method_doc_title" {
+        param "idl_method_name";
+        result > <!--       «$idl_method_name»()       -->\n\n
+    }
+
+    def "func:c99_method_doc_brief" {
+        param "idl_method_name";
+        const "header", "'@brief'";
+        const "cont", "func:idl_method_doc_get_brief($idl_method_name)";
+        choose {
+            when "$cont" {
+                const "cont_normalized", "func:c99_normalize_docstring($cont)";
+                result > «func:column_paragraph($header, $cont_normalized, 80)»\n
+            }
+        }
+    }
+
+    def "func:c99_method_doc_note" {
+        param "idl_method_name";
+        const "header", "'@note'";
+        const "cont", "func:idl_method_doc_get_note($idl_method_name)";
+        choose {
+            when "$cont" {
+                const "cont_normalized", "func:c99_normalize_docstring($cont)";
+                result > «func:column_paragraph($header, $cont_normalized, 80)»
+            }
+        }
+    }
+
+
+    // DOC METHOD PARAMS
+    // -----------------
+
+    def "func:c99_method_doc_params" {
+        param "idl_method_name";
+        result call "c99_method_doc_params" with "idl_method_name", "$idl_method_name";
     }
+    function "c99_method_doc_params" {
+        param "idl_method_name";
+
+        for "func:idl_method_get_params($idl_method_name)" {
+            const "param_name", ".";
+            | «func:c99_method_doc_param($idl_method_name, $param_name)»
+        }
+    }
+
+    def "func:c99_method_doc_param" {
+        param "method_name";
+        param "param_name";
+        const "mode", "func:idl_method_param_get_mode($method_name, $param_name)";
+        const "type", "func:idl_method_param_get_type($method_name, $param_name)";
+        const "doc", "func:idl_method_param_get_doc($method_name, $param_name)";
+        const "header", "func:c99_method_doc_param_header($param_name, $mode)";
+        choose {
+            when "$doc" {
+                const "doc_normalized", "func:c99_normalize_docstring($doc)";
+                result > «func:column_paragraph($header, $doc_normalized, 80)»
+            } otherwise {
+                result > «$header»
+            }
+        }
+    }
+
+    def "func:c99_method_doc_param_header" {
+        param "name";
+        param "mode";
+        result > @param[«$mode»] «$name»
+    }
+
+
+
+    // METHOD DOC THROWS
+    // -----------------
+
+    def "func:c99_method_doc_throws" {
+        param "idl_method_name";
+        result call "c99_method_doc_throws" with "idl_method_name", "$idl_method_name";
+    }
+    function "c99_method_doc_throws" {
+        param "idl_method_name";
+
+        for "func:idl_method_get_throws($idl_method_name)" {
+            const "throw_name", ".";
+            | «func:c99_method_doc_throw($idl_method_name, $throw_name)»
+        }
+    }
+
+    def "func:c99_method_doc_throw" {
+        param "method_name";
+        param "throw_name";
+        const "doc", "func:idl_method_throw_get_doc($method_name, $throw_name)";
+        const "header", "func:c99_method_doc_throw_header($throw_name)";
+        choose {
+            when "$doc" {
+                const "doc_normalized", "func:c99_normalize_docstring($doc)";
+                result > «func:column_paragraph($header, $doc_normalized, 80)»
+            } otherwise {
+                result > «$header»
+            }
+        }
+    }
+
+    def "func:c99_method_doc_throw_header" {
+        param "name";
+        result > @retval «$name»
+    }
+
+
 
     function "method" {
         param "idl_method_name";