From 25d8a977f1f6a169b1f66cee3c42a172d2dcae50 Mon Sep 17 00:00:00 2001
From: Edwin Kofler <edwin@kofler.dev>
Date: Tue, 10 Oct 2023 23:54:15 -0700
Subject: [PATCH 1/2] feat: Add `@deprecated` annotation

---
 shdoc                                         | 22 ++++++++++++-
 .../testcases/@deprecated-standalone.test.sh  | 32 ++++++++++++++++++
 tests/testcases/@deprecated.test.sh           | 33 +++++++++++++++++++
 3 files changed, 86 insertions(+), 1 deletion(-)
 create mode 100644 tests/testcases/@deprecated-standalone.test.sh
 create mode 100644 tests/testcases/@deprecated.test.sh

diff --git a/shdoc b/shdoc
index 5fbdad3..ac758bf 100755
--- a/shdoc
+++ b/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.
diff --git a/tests/testcases/@deprecated-standalone.test.sh b/tests/testcases/@deprecated-standalone.test.sh
new file mode 100644
index 0000000..009e87b
--- /dev/null
+++ b/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
diff --git a/tests/testcases/@deprecated.test.sh b/tests/testcases/@deprecated.test.sh
new file mode 100644
index 0000000..cabda9c
--- /dev/null
+++ b/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

From 651f82c66379b0333ba8226e489a24efae30db32 Mon Sep 17 00:00:00 2001
From: Edwin Kofler <edwin@kofler.dev>
Date: Wed, 11 Oct 2023 01:19:54 -0700
Subject: [PATCH 2/2] docs: Add documentation for `@deprecated`

---
 README.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/README.md b/README.md
index 5b9bc48..fd020e1 100644
--- a/README.md
+++ b/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.