Merge pull request #4 from GB609/feature/internal-sections

allow to mark entire sections as `@internal`

Author: GB609

README.md

@@ -426,10 +426,9 @@ say-hello-world() {
 
 ### `@internal`
 
-When you want to skip documentation generation for a particular function, you can specify this
-`@internal` tag.
-It allows you to have the same style of doc comments across the script and keep internal
-functions hidden from users.
+When you want to skip documentation generation for a particular function, you can specify this `@internal` tag.
+When used in `@section` blocks, all functions until the next `@endsection` or `@section` will be considered internal.  
+It allows you to have the same style of doc comments across the script and keep internal functions hidden from users.
 
 **Example**
 

shdoc

@@ -110,6 +110,11 @@ function process_function(text) {
     }
 
     debug("→ function")
+    if (internal_section){
+        debug("→ → function: contained in internal section, skip")
+        return
+    }
+
     if (is_internal) {
         debug("→ → function: it is internal, skip")
         is_internal = 0
@@ -242,7 +247,6 @@ function reset() {
 function reset_section() {
     debug("→ reset_section()")
 
-    delete section_docblock
     delete docblock_filter
     section = ""
     section_description = ""
@@ -475,6 +479,13 @@ function process_section() {
         debug("→ → no valid section name - skip")
         return;
     }
+    if (is_internal){
+        debug("→ → section marked as internal - skip")
+        internal_section = 1
+        is_internal = 0
+        reset_section();
+        return;
+    }
 
     debug("→ → section: [" section "]")
     debug("→ → section_description: [" section_description "]")
@@ -658,7 +669,12 @@ function debug(msg) {
 
 /^[[:space:]]*# @internal/ {
     debug("→ @internal")
-    is_internal = 1
+    # ignore the flag while we are in an internal section
+    # to prevent dangling values not reset by function blocks
+    # because internal_section is checked first in process_function
+    if (!internal_section){
+        is_internal = 1
+    }
 
     next
 }
@@ -713,13 +729,17 @@ in_description {
   section_description = ""
   section_active = 0
   function_nesting = 2
+  internal_section = 0
 
   next
 }
 
 /^[[:space:]]*# @section/ {
   debug("→ @section")
   sub(/^[[:space:]]*# @section /, "")
+  if (internal_section){
+      internal_section = 0
+  }
   section = $0
   section_active = 1
   function_nesting = 3
@@ -729,10 +749,8 @@ in_description {
 
 /^[[:space:]]*# @example/ {
     debug("→ @example")
-
     in_example = 1
 
-
     next
 }
 

tests/testcases/@section-internal.test.sh

@@ -0,0 +1,85 @@
+# Make an entire section internal.
+# None of its functions should appear in doc or toc.
+# The section itself also shouldn't appear.
+# Internal flag should be cleared by starting a next section, or ending the current one.
+
+tests:put input <<EOF
+# @name Project Name
+# @description Testing @internal on sections...
+
+# @section Section A
+# @description line 1
+# line 2
+# @internal
+
+# @description implicitely internal 1
+internal-a() {
+}
+
+# @description implicitely internal 2
+internal-b() {
+  
+}
+
+# @section Must be visible
+# @description Resets internal flag by @section
+
+# @description must be visible
+b-visible() {
+}
+
+# @section Another internal section
+# @description terminated by @endsection
+# @internal
+
+not-visible() {
+}
+
+# @endsection
+
+visible() {
+}
+
+# @section public section
+# @description with function
+
+# @description must be visible
+visible-in-section() {
+}
+
+# @endsection
+
+EOF
+
+tests:put expected <<EOF
+# Project Name
+
+## Overview
+
+Testing @internal on sections...
+
+## Index
+
+* [Must be visible](#must-be-visible)
+  * [b-visible](#b-visible)
+* [public section](#public-section)
+  * [visible-in-section](#visible-in-section)
+
+## Must be visible
+
+Resets internal flag by @section
+
+### b-visible
+
+must be visible
+
+## public section
+
+with function
+
+### visible-in-section
+
+must be visible
+EOF
+
+assert