Open
Description
Given the following test file:
#!/usr/bin/env bash
# @file testdoc.sh
# @brief Demo
# @description Demonstration.
# @description Something
# something dark side.
#
# @example
# testme()
#
# @noargs
testme() {
echo "Hello"
}
if [[ 1 -eq 2 ]]; then
# @description Another bit of
# comment.
#
# @example
# testus()
#
# @noargs
testus() {
echo "Hello"
}
fiI would expect similar documentation output for both testme and testus - however, I get testus missing its description (but it does include the examples). I can't quite see why this is happening myself, but I'm not familiar with gawk.
Here is the output with debug mode enabled: using:
export SHDOC_DEBUG=1
shdoc testdoc.sh
DEBUG: line: [#!/usr/bin/env bash]
DEBUG: → NOT HANDLED
DEBUG: line: [# @file testdoc.sh]
DEBUG: → @name|@file
DEBUG: line: [# @brief Demo]
DEBUG: → @brief
DEBUG: line: [# @description Demonstration.]
DEBUG: → @description
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: → → in_description: concat
DEBUG: line: []
DEBUG: → → in_description: leave
DEBUG: → handle_description
DEBUG: → → description: added
DEBUG: → break
DEBUG: → handle_description
DEBUG: → reset()
DEBUG: line: [# @description Something]
DEBUG: → @description
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: → → in_description: concat
DEBUG: line: [# something dark side.]
DEBUG: → → in_description: concat
DEBUG: line: [#]
DEBUG: → → in_description: concat
DEBUG: line: [# @example]
DEBUG: → → in_description: leave
DEBUG: → handle_description
DEBUG: → @example
DEBUG: line: [# testme()]
DEBUG: → → in_example: concat
DEBUG: line: [#]
DEBUG: → → in_example: leave
DEBUG: → NOT HANDLED
DEBUG: line: [# @noargs]
DEBUG: → @noargs
DEBUG: line: [testme() {]
DEBUG: → function
DEBUG: → → function: register
DEBUG: → render_docblock
DEBUG: → → func_name: [testme]
DEBUG: → → description: [Something
something dark side.
]
DEBUG: → reset()
DEBUG: line: [ echo "Hello"]
DEBUG: → break
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: line: [}]
DEBUG: → break
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: line: []
DEBUG: → break
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: line: [if [[ 1 -eq 2 ]]; then]
DEBUG: → break
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: line: []
DEBUG: → break
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: line: [ # @description Another bit of]
DEBUG: → @description
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: → → in_description: leave
DEBUG: → handle_description
DEBUG: → NOT HANDLED
DEBUG: line: [ # comment.]
DEBUG: → NOT HANDLED
DEBUG: line: [ #]
DEBUG: → NOT HANDLED
DEBUG: line: [ # @example]
DEBUG: → @example
DEBUG: line: [ # testus()]
DEBUG: → → in_example: concat
DEBUG: line: [ #]
DEBUG: → → in_example: leave
DEBUG: → NOT HANDLED
DEBUG: line: [ # @noargs]
DEBUG: → @noargs
DEBUG: line: [ testus() {]
DEBUG: → function
DEBUG: → → function: register
DEBUG: → render_docblock
DEBUG: → → func_name: [testus]
DEBUG: → → description: [
]
DEBUG: → reset()
DEBUG: line: [ echo "Hello"]
DEBUG: → break
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: line: [ }]
DEBUG: → break
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: line: [fi]
DEBUG: → break
DEBUG: → handle_description
DEBUG: → → description: empty
DEBUG: → reset()
DEBUG: → END {
DEBUG: → → file_title: [testdoc.sh]
DEBUG: → → file_brief: [Demo]
DEBUG: → → file_description: [Demonstration.
]
DEBUG: → END }
# testdoc.sh
Demo
## Overview
Demonstration.
## Index
* [testme](#testme)
* [testus](#testus)
### testme
Something
something dark side.
#### Example
'''bash
testme()
'''
_Function has no arguments._
### testus
#### Example
'''bash
testus()
'''
_Function has no arguments._[note: I did change the backslashes in the outputted code samples to be single quote marks to avoid Github handling it as formatting]
Platform
Docker: debian:bullseye
GNU Awk version: 5.1.0 API: 3.0
shdoc commit version 433a0ba (6th April)
(And before anyone asks, no that is not real in use code, but I've just reduced it down to a test case - there is a reason I've got a function within an if statement and it is formatted by shfmt, checked by shellcheck and runs on in my Bash 5 environment - so I think it's valid code ;) )
( How did I miss #21 ? )
Metadata
Metadata
Assignees
Labels
No labels