feat: Add @deprecated annotation

README.md

@@ -191,6 +191,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.

shdoc

@@ -473,6 +473,17 @@ function render_docblock(func_name, description, docblock) {
  lines[0] = render("h3", func_name)
  }
 
+ if ("deprecated" in docblock) {
+ debug("→ DEPRECATED")
+
+ deprecatedText = "**DEPRECATED.**"
+ if (description != "") {
+ description = deprecatedText " " description
+ } else {
+ push(lines, deprecatedText)
+ }
+ }
+
  if (description != "") {
  push(lines, description)
  # Add empty line to signal end of description.
@@ -639,7 +650,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
@@ -783,6 +794,15 @@ in_example {
  next
 }
 
+/^[[:space:]]*# @deprecated/ {
+ debug("→ @deprecated")
+ sub(/[[:space:]]*# @deprecated /, "")
+
+ docblock_push("deprecated", "")
+
+ 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.

tests/testcases/@deprecated-standalone.test.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+tests:put input <<EOF
+# @name Project Name
+# @brief Brief
+# @description overview
+
+# @deprecated use some other thing instead
+some:first:func() {
+ :
+}
+EOF
+
+tests:put expected <<EOF
+# Project Name
+
+Brief
+
+## Overview
+
+overview
+
+## Index
+
+* [some:first:func](#somefirstfunc)
+
+### some:first:func
+
+**DEPRECATED.**
+EOF
+
+assert

tests/testcases/@deprecated.test.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+tests:put input <<EOF
+# @name Project Name
+# @brief Brief
+# @description overview
+
+# @description My super function. Not thread safe.
+# @deprecated use some other thing instead
+some:first:func() {
+ :
+}
+EOF
+
+tests:put expected <<EOF
+# Project Name
+
+Brief
+
+## Overview
+
+overview
+
+## Index
+
+* [some:first:func](#somefirstfunc)
+
+### some:first:func
+
+**DEPRECATED.** My super function. Not thread safe.
+EOF
+
+assert