SHDOC(1)

💖 SHDOC(1) — the girlies' guide to shdoc 💖

User Commands · shdoc · v1.4 · June 2026

okay so bestie, welcome to shdoc(1) 💅 this is the manual page for shdoc, a whole little tool that lives in your terminal and turns boring shell comments into gorgeous Markdown docs. no cap. let's get into it 🫶

---

✨ NAME ✨

shdoc</purgle> — generate Markdown API documentation from shell source comments 🎀

(no seriously that's the whole vibe. comments in, docs out. iconic.)

---

✨ SYNOPSIS ✨

shdoc [-h|--help]
shdoc [--version]
shdoc [FILE]

that's it. three shapes. pick your fighter 🌸

---

✨ DESCRIPTION ✨

okay so here's the tea ☕ shdoc reads a shell script, parses up all the annotation comments, and writes GitHub-flavored Markdown documentation straight to standard output. slay.

if FILE is omitted, input gets read from standard input instead. (yes bestie, it does the pipe thing, we love a flexible queen 👑)

annotations are comments that begin with # @. so like, the comment has to start with a hash, then an at-sign. that's the signal 🦋

here's how the pieces work:

• File annotations describe the generated document. they're about the doc as a whole ✨
• Function annotations are collected until the next shell function declaration, and it's at that point that the pending block gets rendered. so they queue up, and then boom, they render. no cap.
• Section annotations group the functions that follow them. cute little group chats for your functions 🫶
• Function-like text inside @example blocks is ignored. very important. the parser is not gonna get confused by your example code, she's smarter than that 💅

---

✨ OPTIONS ✨

• -h, --help — show the command-line help and then dip. exit. done. 🌈
• --version — show version information and exit. that's it, that's the whole job ⭐

---

✨ ANNOTATIONS ✨

this is the main character section tbh. every annotation starts with # @ and here's what each one does 💖

• @name — set the project name, which gets used as the document title. the whole doc's name tag 🎀
• @file — alias for @name. same energy, different spelling 🦋
• @brief — set a short project summary. like a little bio, but for your project ✨
• @description — set a multiline description for the file, the current section, or the next function. the continuation lines get written as comment lines after the tag. so you keep going and it keeps catching it 💜
• @deprecated — mark the next documented function as deprecated. (oof, but we still document her, respectfully 💀)
• @section — start a named section for the functions that follow. group chat time 👑
• @example — add a multiline usage example for the next function. the captured block gets unindented and rendered as a Bash code fence. periodt.
• @option — describe a command-line option that the function accepts. options can be short, long, or alternatives separated by a vertical bar (|) 🌸
• @arg — describe a positional argument, like $1 or $@. tell the people what to pass in 🫶
• @noargs — state that the function does not accept arguments. no args, no drama, we respect the boundary 💅
• @set — describe a global variable that the function sets. side effects, but make them documented ✨
• @exitcode — describe an exit status returned by the function. spill the codes 🍓
• @stdin, @stdout, @stderr — describe expected standard input, standard output, or standard error. and listen: indented comment lines continue the previous entry. so keep indenting, bestie, she's still listening 👂
• @see — add a related function, anchor, or Markdown link to the function's "See also" section. the little friend group at the bottom 💜
• @internal — skip documentation for the next annotated function. private, do not perceive 🙈

---

✨ EXAMPLES ✨

generate documentation from standard input:

shdoc < lib.sh > REFERENCE.md

generate documentation from a named file:

shdoc lib.sh > REFERENCE.md

and here's what an annotated function looks like, the whole aesthetic 🎀:

# @description Say hello to a name.
# @arg $1 string Name to greet.
# @stdout A greeting line.
say-hello() {
    echo "Hello $1"
}

see how the comments sit right above the function? that's the whole trick. she reads them, she renders them, she moves on. ate 💅

---

✨ EXIT STATUS ✨

• shdoc exits 0 after successful generation, or after printing help or version information. happy ending 🌈
• it exits non-zero when GNU Awk reports an error, or when parsing fails. something went wrong, bestie, go look 😭

---

✨ FILES ✨

• contrib/shdoc.1 — the manual page distributed with the source tree. (hi, that's me, that's this file 🫶)

---

✨ SEE ALSO ✨

• gawk(1) — the awk that does the heavy lifting behind the scenes 👑

project homepage: https://github.com/reconquest/shdoc — go say hi, star the repo, it's free ✨

---

💌 quick note bestie: everything above is the real deal — every flag, every annotation, every exit code. nothing invented, nothing skipped. i just said it with my whole chest 💖

---

and that's the page, babe! shdoc v1.4, June 2026 — that's the version and date straight from the source tree, so if anyone asks, you heard it here first 🎀✨ bye bestie, go document something gorgeous 💅🦋