From 8b3838878519c5e777067007492aa7fcfdf58319 Mon Sep 17 00:00:00 2001 From: Edwin Kofler Date: Tue, 10 Oct 2023 23:54:15 -0700 Subject: [PATCH 1/3] feat: Add `@deprecated` annotation --- README.md | 39 +++++++++++++++++++++++++++++ examples/readme-example.md | 17 +++++++++---- examples/readme-example.sh | 4 +++ shdoc | 19 +++++++++++++- tests/testcases/@deprecated.test.sh | 25 ++++++++++++++++++ 5 files changed, 98 insertions(+), 6 deletions(-) create mode 100644 tests/testcases/@deprecated.test.sh diff --git a/README.md b/README.md index b2a815d..766819b 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,7 @@ _Output_: [examples/readme-example.md](examples/readme-example.md)

# # @requires foo # @requires bar +# @deprecated use yell-hello instead # # @see validate() # @see [shdoc](https://github.com/reconquest/shdoc). @@ -104,6 +105,10 @@ deeper-level() { echo; } # @description Back up again up-again() { echo; } + +# @description A deprecated function +# @deprecated Because it's old +deprecated-function() { echo; } ~~~ @@ -128,9 +133,12 @@ The project solves lots of problems: * [Sub-section](#sub-section) * [deeper-level](#deeper-level) * [up-again](#up-again) +* [deprecated-function](#deprecated-function) ## say-hello +**DEPRECATED** Use yell-hello instead + My super function. Not thread-safe. @@ -199,6 +207,11 @@ This is nested Back up again +## deprecated-function + +**DEPRECATED** Because it's old + +A deprecated function ~~~ @@ -258,6 +271,19 @@ function super() { } ``` +### `@deprecated` + +Whether or not the function is deprecated. If it is, a short deprecation notice +will be prepended to the description. + +**Example** +```bash +# @deprecated +say-hello() { + ... +} +``` + ### `@section` The name of a section of the file. Can be used to group functions. Creates a paragraph titled with the section name. @@ -392,6 +418,19 @@ set-hello() { } ``` +### `@deprecated` + +Indicates that the function is deprecated + +**Example** + +```bash +# @deprecated use yell-hello-world instead +say-hello-world() { + ... +} +``` + ### `@exitcode` Describes an expected exitcode of the function. diff --git a/examples/readme-example.md b/examples/readme-example.md index b4c8d33..f56089a 100644 --- a/examples/readme-example.md +++ b/examples/readme-example.md @@ -21,6 +21,7 @@ The project solves lots of problems: * [Sub-section](#sub-section) * [deeper-level](#deeper-level) * [up-again](#up-again) +* [deprecated-function](#deprecated-function) ## say-hello @@ -62,17 +63,17 @@ echo "test: $(say-hello World)" * Output 'Oups !' on error. It did it again. -### See also - -* [validate()](#validate) -* [shdoc](https://github.com/reconquest/shdoc). - ### Requires * Some very specific requirements that continue on the next line (indent by a single space to continue) +### See also + +* [validate()](#validate) +* [shdoc](https://github.com/reconquest/shdoc). + ## Sub-section Some grouped functions. @@ -98,3 +99,9 @@ This is nested Back up again +## deprecated-function + +**DEPRECATED** Because it's old + +A deprecated function + diff --git a/examples/readme-example.sh b/examples/readme-example.sh index 687bec3..034fbcf 100644 --- a/examples/readme-example.sh +++ b/examples/readme-example.sh @@ -60,3 +60,7 @@ deeper-level() { echo; } # @description Back up again up-again() { echo; } + +# @description A deprecated function +# @deprecated Because it's old +deprecated-function() { echo; } diff --git a/shdoc b/shdoc index 40d8c6e..64d0245 100755 --- a/shdoc +++ b/shdoc @@ -534,6 +534,14 @@ function render_docblock(func_name, description, docblock, nesting) { lines[0] = render(nesting_top, func_name) } + if (deprecated) { + debug("→ DEPRECATED") + + deprecatedText = "**DEPRECATED**" + push(lines, deprecatedText " " deprecated) + push(lines, "") + } + if (description != "") { push(lines, description) # Add empty line to signal end of description. @@ -729,7 +737,7 @@ function debug(msg) { } in_description { - if (/^[^[[:space:]]*#]|^[[:space:]]*# @[^d]|^[[:space:]]*[^#]|^[[:space:]]*$/) { + if (/^[^[[:space:]]*#]|^[[:space:]]*# @[a-z]+|^[[:space:]]*[^#]|^[[:space:]]*$/ && !match($0, /@description/)) { debug("→ → in_description: leave") in_description = 0 @@ -892,6 +900,15 @@ in_example { next } +/^[[:space:]]*# @deprecated/ { + debug("→ @deprecated") + sub(/[[:space:]]*# @deprecated /, "") + + deprecated = $0 + + next +} + # Previous line added a new docblock item. # Check if current line has the needed indentation # for it to be a multiple lines docblock item. diff --git a/tests/testcases/@deprecated.test.sh b/tests/testcases/@deprecated.test.sh new file mode 100644 index 0000000..5707365 --- /dev/null +++ b/tests/testcases/@deprecated.test.sh @@ -0,0 +1,25 @@ +#!/bin/bash + +tests:put input < Date: Mon, 23 Mar 2026 09:00:20 -0400 Subject: [PATCH 2/3] Render with style instead of explicit "bold" --- shdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shdoc b/shdoc index 64d0245..bc7e4f9 100755 --- a/shdoc +++ b/shdoc @@ -537,7 +537,7 @@ function render_docblock(func_name, description, docblock, nesting) { if (deprecated) { debug("→ DEPRECATED") - deprecatedText = "**DEPRECATED**" + deprecatedText = render("strong", "DEPRECATED") push(lines, deprecatedText " " deprecated) push(lines, "") } From 6823f39b692d6ceb6bed3a0ec02cfdd55ae2cd29 Mon Sep 17 00:00:00 2001 From: Jeremy Brubaker Date: Mon, 23 Mar 2026 11:37:35 -0400 Subject: [PATCH 3/3] Remove @description after it is found This removes the need for the hack that ignores '@description' in a line that is already being processed as part of a description --- shdoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/shdoc b/shdoc index bc7e4f9..f9f75e7 100755 --- a/shdoc +++ b/shdoc @@ -733,11 +733,12 @@ function debug(msg) { handle_description() + sub(/@description/, "") reset() } in_description { - if (/^[^[[:space:]]*#]|^[[:space:]]*# @[a-z]+|^[[:space:]]*[^#]|^[[:space:]]*$/ && !match($0, /@description/)) { + if (/^[^[[:space:]]*#]|^[[:space:]]*# @[a-z]+|^[[:space:]]*[^#]|^[[:space:]]*$/) { debug("→ → in_description: leave") in_description = 0 @@ -749,7 +750,6 @@ in_description { description = concat(description, $0) next } else { - sub(/^[[:space:]]*# @description[[:space:]]*/, "") sub(/^[[:space:]]*#[[:space:]]*/, "") sub(/^[[:space:]]*#$/, "") debug("→ → in_description: concat [" $0 "]")