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)<br/><br/>
 #
 # @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; }
 ~~~
 
 </td>
@@ -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
 ~~~
 
 </td>
@@ -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..f9f75e7 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 = render("strong", "DEPRECATED")
+        push(lines, deprecatedText " " deprecated)
+        push(lines, "")
+    }
+
     if (description != "") {
         push(lines, description)
         # Add empty line to signal end of description.
@@ -725,11 +733,12 @@ function debug(msg) {
 
     handle_description()
 
+    sub(/@description/, "")
     reset()
 }
 
 in_description {
-    if (/^[^[[:space:]]*#]|^[[:space:]]*# @[^d]|^[[:space:]]*[^#]|^[[:space:]]*$/) {
+    if (/^[^[[:space:]]*#]|^[[:space:]]*# @[a-z]+|^[[:space:]]*[^#]|^[[:space:]]*$/) {
         debug("→ → in_description: leave")
 
         in_description = 0
@@ -741,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 "]")
@@ -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 <<EOF
+# @description FUNCTION DESCRIPTION
+#
+# @deprecated this one is ignored
+# @deprecated REASON
+#  ignored line
+func() {
+
+EOF
+
+tests:put expected <<EOF
+## Index
+
+* [func](#func)
+
+## func
+
+**DEPRECATED** REASON
+
+FUNCTION DESCRIPTION
+EOF
+
+assert