From 80d086af6fa25aa875792e46ee109ea99ebaa04b Mon Sep 17 00:00:00 2001
From: Matthias Gatto <matthias.gatto@outscale.com>
Date: Mon, 4 Nov 2024 15:59:34 +0100
Subject: [PATCH] document helpers.sh

Signed-off-by: Matthias Gatto <matthias.gatto@outscale.com>
---
 HACKING.md |  4 ++++
 helper.sh  | 16 ++++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/HACKING.md b/HACKING.md
index f8e4ac6..d3069a5 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -34,3 +34,7 @@ Some rules support multiple languages, like `____func_code____`, which generates
 A relatively easy way to add a feature in Cognac is to start by modifying the generated code (such as "osc-sdk.c", "main.c", etc.). First, make your changes directly in the generated code, ensure it works as expected, and then modify the generator accordingly. This approach helps you know exactly what to look for in the generator.
 
 For exemple, if you modify a function like `parse_thatarg()` in "osc_sdk.c", once the changes are working, you can then search (using a tool like grep) through the generator code to find where `parse_thatarg` is generated. From there, you can add modifications to the generator to make the change permanent and automated.
+
+## helpers.sh
+
+most function in helper.sh have been documented, so go read it if you want to understand some of the most used functions of cognac_gen
diff --git a/helper.sh b/helper.sh
index cb4c299..02dc23c 100644
--- a/helper.sh
+++ b/helper.sh
@@ -1,5 +1,7 @@
 source ./config.sh
 
+# get type from the json of the componant of an argument
+# ex: get_type_direct "$(jq .components.schemas.ReadVmsRequest.properties.VmId < osc-api.json)"
 get_type_direct() {
     arg_info="$1"
     local direct_ref=$(jq -r '.["$ref"]' 2> /dev/null <<< $arg_info)
@@ -81,6 +83,8 @@ get_type_direct() {
     fi
 }
 
+# like get_type, but use full componant json, instead of API function Name
+# ex: get_type3 "$(jq .components.schemas.ReadVmsRequest < osc-api.json)" "VmId"
 get_type3() {
     st_info="$1"
     arg="$2"
@@ -89,6 +93,8 @@ get_type3() {
     return 0
 }
 
+# like get_type, but use full componant name, instead of API function Name
+# ex: get_type2 "ReadVmsRequest" "vmId"
 get_type2() {
     struct="$1"
     arg="$2"
@@ -97,10 +103,12 @@ get_type2() {
     get_type3 "$st_info" "$arg"
 }
 
+# helper for get_type_description
 get_type_description_() {
     jq .properties.$2.description <<< "$1"
 }
 
+# helper for get_type_description
 get_sub_type_description() {
     local st_info=$(jq .components.schemas.$1 < osc-api.json)
     jq .description <<< $st_info | fold -s -w74 | sed "s/^/${2}/"
@@ -132,6 +140,10 @@ get_sub_type_description() {
     done
 }
 
+# Write the description of a componant.
+# useful to genrate SDK Documentation
+# usage: get_type_description "{FULL COMPONANT JSON}" "ARGUMENT"
+# ex: get_type_description "$(jq .components.schemas.ReadVmsRequest < osc-api.json)" "VmId"
 get_type_description() {
     local properties=$(jq .properties.$2 <<< "$1")
     local desc=$(jq .description <<< "$properties")
@@ -147,6 +159,10 @@ get_type_description() {
     fi
 }
 
+
+# Take 2 argument, a API function name, and an argument from it
+# ex: get_type ReadVms VmId
+# will write on stdout the type of VmId in ReadVms
 get_type() {
     x=$2
     func=$1