From b64998d1a463775501a70d125b4d2ae0c4f0a820 Mon Sep 17 00:00:00 2001
From: Ariana Hlavaty <Ariana.Hlavaty@i2group.com>
Date: Wed, 24 Aug 2022 06:08:00 +0100
Subject: [PATCH] Add support for sections in the doc (#54)

* Add support for sections in the doc

* Add spaces
---
 README.md                        | 15 ++++++-
 shdoc                            | 28 ++++++++++++-
 tests/testcases/@section.test.sh | 68 ++++++++++++++++++++++++++++++++
 3 files changed, 108 insertions(+), 3 deletions(-)
 create mode 100644 tests/testcases/@section.test.sh

diff --git a/README.md b/README.md
index 9a2e3d4..24fd17d 100644
--- a/README.md
+++ b/README.md
@@ -140,8 +140,9 @@ A brief line about the project. Can be specified once in the beginning of the fi
 
 ### `@description`
 
-A multiline description of the project/function.
-* Can be specified once for the whole file in the begibeginning of the file.
+A multiline description of the project/section/function.
+* Can be specified once for the whole file in the beginning of the file.
+* Can be specified once for a section of the file. See [@section](#section).
 * Can be specified once for on top of a function definition.
 
 **Example**
@@ -157,6 +158,16 @@ function super() {
 }
 ```
 
+### `@section`
+
+The name of a section of the file. Can be used to group functions.
+
+**Example**
+```bash
+# @section My utilities functions
+# @description The following functions can be used to solve problems.
+```
+
 ### `@example`
 
 A multiline example of the function usage. Can be specified only alongside the function definition.
diff --git a/shdoc b/shdoc
index dc7f24f..5613dbe 100755
--- a/shdoc
+++ b/shdoc
@@ -131,6 +131,12 @@ function handle_description() {
         return;
     }
 
+    if (section != "" && section_description == "") {
+      debug("→ → description: added")
+      section_description = description
+      return;
+    }
+
     if (file_description == "") {
         debug("→ → description: added")
         file_description = description
@@ -185,7 +191,19 @@ function render_docblock(func_name, description, docblock) {
     debug("→ → func_name: [" func_name "]")
     debug("→ → description: [" description "]")
 
-    lines[0] = render("h3", func_name)
+    if (section != "") {
+      lines[0] = render("h2", section)
+      if (section_description != "") {
+        push(lines, section_description)
+      }
+      section = ""
+      section_description = ""
+      push(lines, render("h3", func_name))
+      push(lines, "")
+    } else {
+      lines[0] = render("h3", func_name)
+    }
+    
     if (description != "") {
         push(lines, description)
     }
@@ -343,6 +361,14 @@ in_description {
     }
 }
 
+/^[[:space:]]*# @section/ {
+  debug("→ @section")
+  sub(/^[[:space:]]*# @section /, "")
+  section = $0
+
+  next
+}
+
 /^[[:space:]]*# @example/ {
     debug("→ @example")
 
diff --git a/tests/testcases/@section.test.sh b/tests/testcases/@section.test.sh
new file mode 100644
index 0000000..fa57fb8
--- /dev/null
+++ b/tests/testcases/@section.test.sh
@@ -0,0 +1,68 @@
+
+tests:put input <<EOF
+# @name Project Name
+# @brief Brief
+# @description a
+# b
+
+# @section Section A
+# @description a
+# a
+
+# @description func a
+# line a 2
+# @noargs
+a() {
+}
+
+# @section Section B
+# @description b
+
+# @description func b
+# ab
+# @noargs
+b() {
+}
+EOF
+
+tests:put expected <<EOF
+# Project Name
+
+Brief
+
+## Overview
+
+a
+b
+
+## Index
+
+* [a](#a)
+* [b](#b)
+
+## Section A
+
+a
+a
+
+### a
+
+func a
+line a 2
+
+_Function has no arguments._
+
+## Section B
+
+b
+
+### b
+
+func b
+ab
+
+_Function has no arguments._
+
+EOF
+
+assert