From fd82d5f724f3dff8ee6607cabf207a9d1b2baef8 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  | 18 ++++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/HACKING.md b/HACKING.md
index f8e4ac6..b0a36fd 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 functions in helper.sh are documented, so read through it if you want to understand some of the most commonly used functions in cognac_gen.
diff --git a/helper.sh b/helper.sh
index cb4c299..c721d4d 100644
--- a/helper.sh
+++ b/helper.sh
@@ -1,5 +1,7 @@
 source ./config.sh
 
+# Retrieve the type from the JSON of a component for a given 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,9 @@ get_type_direct() {
     fi
 }
 
+# Retrieve the type directly from the full component JSON rather than using the
+# API function Name in get_type.
+# ex: get_type3 "$(jq .components.schemas.ReadVmsRequest < osc-api.json)" "VmId"
 get_type3() {
     st_info="$1"
     arg="$2"
@@ -89,6 +94,9 @@ get_type3() {
     return 0
 }
 
+# Retrieve the type directly from the full component JSON rather than using the
+# API function name in get_type.
+# ex: get_type2 "ReadVmsRequest" "vmId"
 get_type2() {
     struct="$1"
     arg="$2"
@@ -97,10 +105,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 +142,10 @@ get_sub_type_description() {
     done
 }
 
+# Write the description of a component.
+# useful for generating 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 +161,10 @@ get_type_description() {
     fi
 }
 
+
+# Takes two arguments: an API function name and one of its arguments.
+# ex: get_type ReadVms VmId
+# will write on stdout the type of VmId in ReadVms
 get_type() {
     x=$2
     func=$1