From 8d2894180252b9b469d893037232cae36d6fb5e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pierre-Yves=20Landur=C3=A9?= <pierre-yves@landure.fr>
Date: Mon, 31 Jul 2023 07:18:48 +0200
Subject: [PATCH] Add support for @option tag (partially close #51) (#64)

* Add missing empty line in overview section output.

* - Add @option for short option (-o) and long options (--option).
- Revamp description and titles processing to normalize "\n" usage and remove empty lines at the start and end of description.
- Add dt and dd rendering styles.

* Add @option to README and example.

* Remove useless description  self-assignation.

* Fix readme width after adding too long @option

* Fix readme width by shorting @see example.

* Fix missing < and > escaping in outputted markdown
---
 README.md                       |  60 ++++++++
 examples/readme-example.md      |  13 +-
 examples/readme-example.sh      |   6 +-
 shdoc                           | 262 ++++++++++++++++++++++++++------
 tests/testcases/@option.test.sh | 126 +++++++++++++++
 tests/testcases/@stderr.test.sh |   1 +
 tests/testcases/@stdin.test.sh  |   1 +
 tests/testcases/@stdout.test.sh |   1 +
 8 files changed, 425 insertions(+), 45 deletions(-)
 create mode 100644 tests/testcases/@option.test.sh

diff --git a/README.md b/README.md
index b5b6c0d..5b9bc48 100644
--- a/README.md
+++ b/README.md
@@ -45,14 +45,25 @@ _Output_: [examples/readme-example.md](examples/readme-example.md)<br/><br/>
 # @example
 #    echo "test: $(say-hello World)"
 #
+#
+# @option -h | --help Display help.
+# @option -v<value> | --value=<value> Set a value.
+#
 # @arg $1 string A value to print
 #
+# @stdout Output 'Hello $1'.
+#   It hopes you say Hello back.
+# @stderr Output 'Oups !' on error.
+#   It did it again.
+#
 # @exitcode 0 If successful.
 # @exitcode 1 If an empty string passed.
 #
 # @see validate()
+# @see [shdoc](https://github.com/reconquest/shdoc).
 say-hello() {
     if [[ ! "$1" ]]; then
+        echo "Oups !" >&2
         return 1;
     fi
 
@@ -92,6 +103,16 @@ Not thread-safe.
 echo "test: $(say-hello World)"
 ```
 
+#### Options
+
+* **-h** | **--help**
+
+  Display help.
+
+* **-v\<value\>** | **--value=\<value\>**
+
+  Set a value.
+
 #### Arguments
 
 * **$1** (string): A value to print
@@ -101,9 +122,21 @@ echo "test: $(say-hello World)"
 * **0**: If successful.
 * **1**: If an empty string passed.
 
+#### Output on stdout
+
+* Output 'Hello $1'.
+  It hopes you say Hello back.
+
+#### Output on stderr
+
+* Output 'Oups !' on error.
+  It did it again.
+
 #### See also
 
 * [validate()](#validate)
+* [shdoc](https://github.com/reconquest/shdoc).
+
 ~~~
 
 </td>
@@ -181,12 +214,31 @@ say-hello() {
 }
 ```
 
+### `@option`
+
+A description of an option expected to be passed while calling the function.
+Can be specified multiple times to describe any number of arguments.
+If an option argument is expected, it must be specified between `<` and `>`
+
+**Example**
+
+```bash
+# @description Says hi to a given person.
+# @option -h A short option.
+# @arg --value=<value> A long option with argument.
+# @arg -v<value> | --value <value> A long option with short option alternative.
+say-hello() {
+    ...
+}
+```
+
 ### `@arg`
 
 A description of an argument expected to be passed while calling the function.
 Can be specified multiple times to describe any number of arguments.
 
 **Example**
+
 ```bash
 # @description Says hi to a given person.
 # @arg $1 string A person's name.
@@ -201,6 +253,7 @@ say-hello() {
 A note that the function does not expect any arguments to be passed.
 
 **Example**
+
 ```bash
 # @description Says 'hello world'.
 # @noargs
@@ -215,6 +268,7 @@ A description of a global variable that is set while calling the function.
 Can be specified multiple times to describe any number of variables
 
 **Example**
+
 ```bash
 # @description Sets hello to the variable REPLY
 # @set REPLY string Greeting message.
@@ -229,6 +283,7 @@ Describes an expected exitcode of the function.
 Can be specified multiple times to describe all possible exitcodes and their conditions.
 
 **Example**
+
 ```bash
 # @description Says 'hello world'.
 # @exitcode 0 If successful.
@@ -243,6 +298,7 @@ say-hello-world() {
 The expected input to the function call from `stdin` (usually the terminal or command line)
 
 **Example**
+
 ```bash
 # @description Asks name.
 # @stdin The users name from the terminal/command line.
@@ -256,6 +312,7 @@ say-hello-world() {
 An expected output of the function call.
 
 **Example**
+
 ```bash
 # @description Says 'hello world'.
 # @stdout A path to a temporary file with the message.
@@ -269,6 +326,7 @@ say-hello-world() {
 An expected output of the function call on `/dev/stderr`.
 
 **Example**
+
 ```bash
 # @description Says 'hello world'.
 # @stderr A error message when world is not available.
@@ -282,6 +340,7 @@ say-hello-world() {
 Create a link on the given function in the "See Also" section.
 
 **Example**
+
 ```bash
 # @see say-hello
 # @see text with [markdown link](./other-file#other-function)
@@ -298,6 +357,7 @@ It allows you to have the same style of doc comments across the script and keep
 functions hidden from users.
 
 **Example**
+
 ```bash
 # @internal
 show-msg() {
diff --git a/examples/readme-example.md b/examples/readme-example.md
index 397f015..3f41e0a 100644
--- a/examples/readme-example.md
+++ b/examples/readme-example.md
@@ -25,6 +25,16 @@ Not thread-safe.
 echo "test: $(say-hello World)"
 ```
 
+#### Options
+
+* **-h** | **--help**
+
+  Display help.
+
+* **-v\<value\>** | **--value=\<value\>**
+
+  Set a value.
+
 #### Arguments
 
 * **$1** (string): A value to print
@@ -47,4 +57,5 @@ echo "test: $(say-hello World)"
 #### See also
 
 * [validate()](#validate)
-* Documentation generated using [shdoc](https://github.com/reconquest/shdoc).
\ No newline at end of file
+* [shdoc](https://github.com/reconquest/shdoc).
+
diff --git a/examples/readme-example.sh b/examples/readme-example.sh
index b6bd512..f5a3bab 100644
--- a/examples/readme-example.sh
+++ b/examples/readme-example.sh
@@ -14,6 +14,10 @@
 # @example
 #    echo "test: $(say-hello World)"
 #
+#
+# @option -h | --help Display help.
+# @option -v<value> | --value=<value> Set a value.
+#
 # @arg $1 string A value to print
 #
 # @stdout Output 'Hello $1'.
@@ -25,7 +29,7 @@
 # @exitcode 1 If an empty string passed.
 #
 # @see validate()
-# @see Documentation generated using [shdoc](https://github.com/reconquest/shdoc).
+# @see [shdoc](https://github.com/reconquest/shdoc).
 say-hello() {
     if [[ ! "$1" ]]; then
         echo "Oups !" >&2
diff --git a/shdoc b/shdoc
index 13ae5b9..3300061 100755
--- a/shdoc
+++ b/shdoc
@@ -7,16 +7,19 @@ BEGIN {
     }
 
     styles["github", "h1", "from"] = ".*"
-    styles["github", "h1", "to"] = "# &"
+    styles["github", "h1", "to"] = "# &\n"
 
     styles["github", "h2", "from"] = ".*"
-    styles["github", "h2", "to"] = "## &"
+    styles["github", "h2", "to"] = "## &\n"
 
     styles["github", "h3", "from"] = ".*"
-    styles["github", "h3", "to"] = "### &"
+    styles["github", "h3", "to"] = "### &\n"
 
     styles["github", "h4", "from"] = ".*"
-    styles["github", "h4", "to"] = "#### &"
+    styles["github", "h4", "to"] = "#### &\n"
+
+    styles["github", "strong", "from"] = ".*"
+    styles["github", "strong", "to"] = "**&**"
 
     styles["github", "code", "from"] = ".*"
     styles["github", "code", "to"] = "```&"
@@ -35,6 +38,12 @@ BEGIN {
     styles["github", "li", "from"] = ".*"
     styles["github", "li", "to"] = "* &"
 
+    styles["github", "dt", "from"] = ".*"
+    styles["github", "dt", "to"] = "* &\n"
+
+    styles["github", "dd", "from"] = "^.*$"
+    styles["github", "dd", "to"] = "  &"
+
     styles["github", "i", "from"] = ".*"
     styles["github", "i", "to"] = "_&_"
 
@@ -175,19 +184,25 @@ function reset() {
 
 function handle_description() {
     debug("→ handle_description")
+
+    # Remove empty lines at the start of description.
+    sub(/^[[:space:]\n]*\n/, "", description)
+    # Remove empty lines at the end of description.
+    sub(/[[:space:]\n]*$/, "", description)
+
     if (description == "") {
         debug("→ → description: empty")
         return;
     }
 
     if (section != "" && section_description == "") {
-      debug("→ → description: added")
+      debug("→ → section description: added")
       section_description = description
       return;
     }
 
     if (file_description == "") {
-        debug("→ → description: added")
+        debug("→ → file description: added")
         file_description = description
         return;
     }
@@ -204,7 +219,7 @@ function concat(x, text) {
 }
 
 function push(arr, value) {
-    arr[length(arr)+1] = value
+    arr[length(arr)] = value
 }
 
 function join(arr) {
@@ -220,7 +235,7 @@ function join(arr) {
 }
 
 # @description Remove leading and trailing space from line(s) of text.
-# @arg text A text.
+# @param text A text.
 # @return The trimmed text.
 function trim(text) {
     gsub(/(^[[:blank:]]+|[[:blank:]]+$)/, "", text)
@@ -239,11 +254,33 @@ function docblock_concat(key, value) {
     }
 }
 
+# @description Add a value as the new last item of a docblock.
+#
+# @param docblock_name  Name of the modified docblock.
+# @param value          Added item value.
+#
+# @set docblock[docblock_name] docblock with value added as its last item.
 function docblock_push(key, value) {
-    docblock[key][length(docblock[key])+1] = value
+    new_item_index = length(docblock[key])
+    # Reinitialize docblock key value if it is empty to allow for array storage.
+    if(new_item_index == 0)
+    {
+        delete docblock[key]
+    }
+    if(isarray(value))
+    {
+
+        # Value is an array. Add its contents key by key to the docblock.
+        # Note that is only allow for single dimension value array.
+        for (i in value) {
+            docblock[key][new_item_index][i] = value[i]
+        }
+    }
+    else {
+        docblock[key][new_item_index] = value
+    }
 }
 
-
 # @description Append a text to the last item of a docblock.
 #
 # @param docblock_name  Name of the modified docblock.
@@ -252,7 +289,13 @@ function docblock_push(key, value) {
 # @set docblock[docblock_name] docblock with text appended to last item.
 function docblock_append(docblock_name, text) {
     # Detect last docblock item index.
-    last_item_index = length(docblock[docblock_name])
+    last_item_index = length(docblock[docblock_name]) - 1
+
+    # Ensure there is no issue if docblock[docblock_name] is empty.
+    if(last_item_index < 0) {
+        last_item_index = 0
+    }
+
     # Append text to last docblock item.
     docblock[docblock_name][last_item_index] = docblock[docblock_name][last_item_index] text
 }
@@ -265,11 +308,12 @@ function docblock_append(docblock_name, text) {
 #
 # @stdout A unordered list of the dockblock entries.
 function render_docblock_list(docblock, docblock_name, title) {
-    push(lines, render("h4", title) "\n")
+    push(lines, render("h4", title))
     # Initialize list item.
     item = ""
     # For each dockblock line.
     for (i in docblock[docblock_name]) {
+        docblock[docblock_name][i]
         # Ident additionnal lines to add them to the markdown list item.
         gsub(/\n/, "\n  ", docblock[docblock_name][i])
         item = render("li", docblock[docblock_name][i])
@@ -280,38 +324,148 @@ function render_docblock_list(docblock, docblock_name, title) {
     push(lines, "")
 }
 
+# @description Process a text as an @option tag content.
+#   The @option accept the folling format:
+#
+#   # @option <option> <description>
+#
+#   Where <option> allows:
+#
+#   - **-o** : single letter short option, signaled by single dash.
+#       Allow for all letters in the A-Z and a-z ranges.
+#   - **-o<argument> : single letter short option with argument.
+#       Argument must be between < and >.
+#   - **--option** : long option, signaled by double dash.
+#   - **--option=<argument> : long option with argument.
+#       Argument must be between < and >.
+#   - **-o | --option** : long option with short option version.
+#
+#   To achieve this, process_at_option uses a complex regular expression.
+#   which is decomposed below:
+#
+#   ```awk
+#   # Set optional arg (- and -- options) regex
+#   short_option_regex = "-[[:alnum:]]([[:blank:]]*<[^>]+>)?"
+#   long_option_regex = "--[[:alnum:]][[:alnum:]-]*((=|[[:blank:]]+)<[^>]+>)?"
+#   pipe_separator_regex = "([[:blank:]]*\\|?[[:blank:]]+)"
+#   description_regex = "([^[:blank:]|<-].*)?"
+#   
+#   # Build regex matching all options
+#   short_or_long_option_regex = sprintf("(%s|%s)", short_option_regex, long_option_regex)
+# 
+#   # Build regex matching multiple options separated by spaces or pipe.
+#   all_options_regex = sprintf("(%s%s)+", short_or_long_option_regex, pipe_separator_regex)
+# 
+#   # Build final regex.
+#   optional_arg_regex = sprintf("^(%s)%s$", all_options_regex, description_regex)
+#   ```
+# 
+#   Final regex with non-matching groups (unsupported by gawk).
+# 
+#   `^((?:(?:-[[:alnum:]](?:[[:blank:]]*<[^>]+>)?|--[[:alnum:]][[:alnum:]-]*(?:(?:=|[[:blank:]]+)<[^>]+>)?)(?:[[:blank:]]*\|?[[:blank:]]+))+)([^[:blank:]|<-].*)?$`
+#
+# @param text   The text to process as an @option entry.
+# 
+# @set dockblock["option"] A docblock for correctly formated options.
+# @set dockblock["option-bad"] A docblock for badly formated options.
+function process_at_option(text) {
+
+    # Test if @arg is a command-line option description (starting by - or --).
+    if(match(text, /^(((-[[:alnum:]]([[:blank:]]*<[^>]+>)?|--[[:alnum:]][[:alnum:]-]*((=|[[:blank:]]+)<[^>]+>)?)([[:blank:]]*\|?[[:blank:]]+))+)([^[:blank:]|<-].*)?$/, contents)) {
+        debug(" → → found correctly formated @option.")
+
+        # Fetch matched values.
+        term = trim(contents[1])
+        option_description["definition"] = trim(contents[8])
+
+        # Trim spaces around pipes.
+        gsub(/[[:blank:]]+\|[[:blank:]]+/, " | ", term)
+
+        # Add term (-option | --option) to option description.
+        option_description["term"] = term
+
+        # Add values to optional-arg docblock.
+        docblock_push("option", option_description)
+
+    } else {
+        # Warn of badly formated @option.
+        warn("Invalid format: @option " text)
+
+        # For backward compatibility,
+        # process badly formated @arg as badly formated option.
+        docblock_push("option-bad", text)
+    }
+}
+
 function render_docblock(func_name, description, docblock) {
     debug("→ render_docblock")
     debug("→ → func_name: [" func_name "]")
     debug("→ → description: [" description "]")
 
+    # Reset lines variable to allow for a new array creation.
+    delete lines
+
     if (section != "") {
       lines[0] = render("h2", section)
       if (section_description != "") {
         push(lines, section_description)
+        # Add empty line to signal end of description.
+        push(lines, "")
       }
       section = ""
       section_description = ""
       push(lines, render("h3", func_name))
-      push(lines, "")
     } else {
       lines[0] = render("h3", func_name)
     }
-    
+
     if (description != "") {
         push(lines, description)
+        # Add empty line to signal end of description.
+        push(lines, "")
     }
 
     if ("example" in docblock) {
         push(lines, render("h4", "Example"))
-        push(lines, "\n" render("code", "bash"))
+        push(lines, render("code", "bash"))
         push(lines, unindent(docblock["example"]))
         push(lines, render("/code"))
         push(lines, "")
     }
 
+    if ("option" in docblock || "option-bad" in docblock) {
+        push(lines, render("h4", "Options"))
+
+        if ("option" in docblock) {
+            for (i in docblock["option"]) {
+                # Add strong around options, but exclude pipes.
+                term = render("strong", docblock["option"][i]["term"])
+                gsub(/[[:blank:]]+\|[[:blank:]]+/, "** | **", term)
+                # Escape < an >.
+                gsub(/</, "\\<", term)
+                gsub(/>/, "\\>", term)
+                # Render definition list term (dt)
+                item = render("dt", term)
+                push(lines, item)
+                # Render definition list definition (dd)
+                item = render("dd", docblock["option"][i]["definition"] "\n")
+                push(lines, item)
+            }
+        }
+
+        if ("option-bad" in docblock) {
+            for (i in docblock["option-bad"]) {
+                item = render("li", docblock["option-bad"][i])
+                push(lines, item)
+            }
+
+            # Add empty line to signal end of list in markdown.
+            push(lines, "")
+        }
+    }
+
     if ("arg" in docblock) {
-        push(lines, render("h4", "Arguments") "\n")
+        push(lines, render("h4", "Arguments"))
 
         # Sort args by indexes (i.e. by argument number.)
         asorti(docblock["arg"], sorted_indexes)
@@ -330,31 +484,34 @@ function render_docblock(func_name, description, docblock) {
     }
 
     if ("noargs" in docblock) {
-        push(lines, render("i", "Function has no arguments.") "\n")
+        push(lines, render("i", "Function has no arguments."))
+
+        # Add empty line to signal end of list in markdown.
+        push(lines, "")
     }
 
     if ("set" in docblock) {
-        push(lines, render("h4", "Variables set") "\n")
+        push(lines, render("h4", "Variables set"))
         for (i in docblock["set"]) {
             item = docblock["set"][i]
             item = render("set", item)
             item = render("li", item)
-            if (i == length(docblock["set"])) {
-                item = item "\n"
-            }
             push(lines, item)
         }
+
+        # Add empty line to signal end of list in markdown.
+        push(lines, "")
     }
 
     if ("exitcode" in docblock) {
-        push(lines, render("h4", "Exit codes") "\n")
+        push(lines, render("h4", "Exit codes"))
         for (i in docblock["exitcode"]) {
             item = render("li", render("exitcode", docblock["exitcode"][i]))
-            if (i == length(docblock["exitcode"])) {
-                item = item "\n"
-            }
             push(lines, item)
         }
+
+        # Add empty line to signal end of list in markdown.
+        push(lines, "")
     }
 
     if ("stdin" in docblock) {
@@ -370,20 +527,18 @@ function render_docblock(func_name, description, docblock) {
     }
 
     if ("see" in docblock) {
-        push(lines, render("h4", "See also") "\n")
+        push(lines, render("h4", "See also"))
         for (i in docblock["see"]) {
             item = render("li", render_toc_link(docblock["see"][i]))
-            if (i == length(docblock["see"])) {
-                item = item "\n"
-            }
             push(lines, item)
         }
-    }
 
+        # Add empty line to signal end of list in markdown.
+        push(lines, "")
+    }
 
     result = join(lines)
-    delete lines
-    return join(lines)
+    return result
 }
 
 function debug(msg) {
@@ -432,9 +587,6 @@ function debug(msg) {
 in_description {
     if (/^[^[[:space:]]*#]|^[[:space:]]*# @[^d]|^[[:space:]]*[^#]|^[[:space:]]*$/) {
         debug("→ → in_description: leave")
-        if (!match(description, /\n$/)) {
-            description = description "\n"
-        }
 
         in_description = 0
 
@@ -481,6 +633,24 @@ in_example {
 
 }
 
+# Select @option lines with content.
+/^[[:blank:]]*#[[:blank:]]+@option[[:blank:]]+[^[:blank:]]/ {
+    debug("→ @option")
+    option_text = $0
+
+    # Remove '# @option ' tag.
+    sub(/^[[:blank:]]*#[[:blank:]]+@option[[:blank:]]+/, "", option_text)
+
+    # Trim text.
+    option_text = trim(option_text)
+
+    # Process @option text.
+    process_at_option(option_text)
+
+    # Stop processing current line, and process next line.
+    next
+}
+
 # Select @arg lines with content.
 /^[[:blank:]]*#[[:blank:]]+@arg[[:blank:]]+[^[:blank:]]/ {
     debug("→ @arg")
@@ -514,7 +684,13 @@ in_example {
     }
 
     # Ignore badly formated @arg.
-    warn("Invalid format: @arg " arg_text)
+    warn("Invalid format, processed as @option: @arg " arg_text)
+
+    # Process @arg as option, if badly formated.
+    process_at_option(arg_text)
+
+    # Stop processing current line, and process next line.
+    next
 }
 
 # Select @noargs line with no additionnal text.
@@ -559,7 +735,7 @@ in_example {
 multiple_line_docblock_name {
     # Check if current line indentation does match the previous line docblock item.
     if ($0 ~ multiple_line_identation_regex ) {
-        debug("→ @" multiple_line_docblock_name)
+        debug("→ @" multiple_line_docblock_name " - new line")
         
         # Current line has the same indentation as the stderr section.
     
@@ -645,21 +821,21 @@ END {
         print render("h1", file_title)
 
         if (file_brief != "") {
-            print "\n" file_brief
+            print file_brief "\n" 
         }
 
         if (file_description != "") {
-            print "\n" render("h2", "Overview")
-            print "\n" file_description
+            print render("h2", "Overview")
+            print file_description "\n" 
         }
     }
 
     if (toc != "") {
-        print render("h2", "Index") "\n"
-        print toc
+        print render("h2", "Index")
+        print toc "\n" 
     }
 
-    print "\n" doc
+    print doc
 
     ## TODO: add examples section
 }
diff --git a/tests/testcases/@option.test.sh b/tests/testcases/@option.test.sh
new file mode 100644
index 0000000..386852e
--- /dev/null
+++ b/tests/testcases/@option.test.sh
@@ -0,0 +1,126 @@
+#!/bin/bash
+# @file test/testcases/@optional-arguments.test.sh
+# @author Pierre-Yves Landuré < contact at biapy dot fr >
+# @brief Test cases for @option keyword with options.
+# @description
+#   Test these @option comportements:
+#   - single dash short option (-o)
+#   - single dash numeric short option (-2)
+#   - double dash long option (--option)
+#   - short option with value joined to letter.
+#   - short option with value separated by space.
+#   - long option with value separated by =.
+#   - long option with value separated by space.
+#   - long option with alternative short option syntax.
+#   - appears before numeric argument list.
+#   - appears between @example and @set sections.
+
+tests:put input <<EOF
+# @name shdoc @option tests for options
+# @brief Test @option functionnality for options.
+# @description Tests for shdoc processing of @option keyword.
+# @option -2 Run twice as fast.
+# @option -h Show help message.
+# @option --help Show help message.
+# @option -h | --help Show help message.
+# @option -v<my value> Set a value for short option (joined).
+# @option -v <my value> Set a value for short option (space separated).
+# @option option with invalid format.
+# @option --value=<my value> Set a value for long option (= joined).
+# @set ARG_TESTED A variable set by the function.
+# @option ---another option with invalid format.
+# @option --value <my value> Set a value for long option (space separated).
+# @example
+#   test-arg 'my-tested-argument'
+#
+# @option -v <my value> | --value <my value> Set a value.
+# @option -v<my value> | --value=<my value> Set a value (joined).
+# @option --value=<my value>  |  -v<my value> |   --longer-value <my value> Set a value via three different options.
+# @arg -v<my value> | --value=<my value> Set a value described by @arg.
+test-arg() {
+}
+EOF
+
+tests:put expected <<EOF
+# shdoc @option tests for options
+
+Test @option functionnality for options.
+
+## Overview
+
+Tests for shdoc processing of @option keyword.
+
+## Index
+
+* [test-arg](#test-arg)
+
+### test-arg
+
+Tests for shdoc processing of @option keyword.
+
+#### Example
+
+\`\`\`bash
+test-arg 'my-tested-argument'
+\`\`\`
+
+#### Options
+
+* **-2**
+
+  Run twice as fast.
+
+* **-h**
+
+  Show help message.
+
+* **--help**
+
+  Show help message.
+
+* **-h** | **--help**
+
+  Show help message.
+
+* **-v\\<my value\\>**
+
+  Set a value for short option (joined).
+
+* **-v \\<my value\\>**
+
+  Set a value for short option (space separated).
+
+* **--value=\\<my value\\>**
+
+  Set a value for long option (= joined).
+
+* **--value \\<my value\\>**
+
+  Set a value for long option (space separated).
+
+* **-v \\<my value\\>** | **--value \\<my value\\>**
+
+  Set a value.
+
+* **-v\\<my value\\>** | **--value=\\<my value\\>**
+
+  Set a value (joined).
+
+* **--value=\\<my value\\>** | **-v\\<my value\\>** | **--longer-value \\<my value\\>**
+
+  Set a value via three different options.
+
+* **-v\\<my value\\>** | **--value=\\<my value\\>**
+
+  Set a value described by @arg.
+
+* option with invalid format.
+* ---another option with invalid format.
+
+#### Variables set
+
+* **ARG_TESTED** (A): variable set by the function.
+
+EOF
+
+assert
diff --git a/tests/testcases/@stderr.test.sh b/tests/testcases/@stderr.test.sh
index 7ad2fe1..e341ab2 100644
--- a/tests/testcases/@stderr.test.sh
+++ b/tests/testcases/@stderr.test.sh
@@ -50,6 +50,7 @@ Test @stderr functionnality.
 ## Overview
 
 Tests for shdoc processing of @stderr keyword.
+
 ## Index
 
 * [test-stderr](#test-stderr)
diff --git a/tests/testcases/@stdin.test.sh b/tests/testcases/@stdin.test.sh
index da7a3df..0593eed 100644
--- a/tests/testcases/@stdin.test.sh
+++ b/tests/testcases/@stdin.test.sh
@@ -39,6 +39,7 @@ Test @stdin functionnality.
 ## Overview
 
 Tests for shdoc processing of @stdin keyword.
+
 ## Index
 
 * [test-stdin](#test-stdin)
diff --git a/tests/testcases/@stdout.test.sh b/tests/testcases/@stdout.test.sh
index 613f09a..ccc5ec2 100644
--- a/tests/testcases/@stdout.test.sh
+++ b/tests/testcases/@stdout.test.sh
@@ -38,6 +38,7 @@ Test @stdout functionnality.
 ## Overview
 
 Tests for shdoc processing of @stdout keyword.
+
 ## Index
 
 * [test-stdout](#test-stdout)