3# doxygen-bash-docfilter.awk
5# Documentation-led Doxygen preprocessor for Bash, implemented as a single
8# The filter intentionally documents only symbols with Doxygen-style Bash
9# comment blocks. It is permissive about Bash formatting so author intent is
10# not lost because of whitespace, indentation, or a harmless declaration style
13# Supported primary comment style:
18# Supported documented declarations include:
26# declare -r NAME=value
27# declare -a NAME=(...)
28# declare -A NAME=(...)
38# This is not a shell parser. It is a documentation compiler for the subset of
39# Bash declarations that can reasonably follow a Doxygen block.
42 strict = (strict ? strict : 0)
43 keep_blanks = (compact ? 0 : 1)
45 for (arg_index = 1; arg_index < ARGC; arg_index++) {
46 if (ARGV[arg_index] ==
"--strict") {
49 }
else if (ARGV[arg_index] ==
"--compact") {
63 doc_namespace_conflict =
""
65 doc_module_conflict =
""
66 doc_module_invalid =
""
67 doc_module_malformed =
""
72 delete param_doc_lines
73 delete emitted_param_names
77 sub(/^[ \t\r\n]+/,
"", s)
78 sub(/[ \t\r\n]+$/,
"", s)
82function emit_blank() {
88function warn(message) {
89 print FILENAME
":" FNR
": warning: " message >
"/dev/stderr"
93function fail_or_warn(message) {
100function is_blank(line) {
101 return (line ~ /^[ \t]*$/)
104function is_doc_line(line) {
105 return (line ~ /^[ \t]*##([ \t]|$)/)
108function is_transparent_annotation(line, s) {
110 return (s ~ /^#[ \t]*shellcheck[ \t]+disable=SC[0-9]+([ \t]*,[ \t]*SC[0-9]+)*[ \t]*$/)
113function strip_doc_marker(line, s) {
115 sub(/^[ \t]*##[ \t]?/,
"", s)
119function is_param_directive(meta) {
120 return (meta ~ /^@param(\[(in|out|in,out)\])?[ \t]+/)
123function record_module_directive(meta, directive, s, module_name) {
126 sub(
"^" directive,
"", s)
128 if (s !~ /^[ \t]+/) {
129 if (doc_module_malformed ==
"") {
130 doc_module_malformed = directive
136 if (s ==
"" || s ~ /[ \t]/) {
137 if (doc_module_malformed ==
"") {
138 doc_module_malformed = directive
144 if (!is_valid_identifier(module_name)) {
145 if (doc_module_invalid ==
"") {
146 doc_module_invalid = module_name
151 if (doc_module ==
"") {
152 doc_module = module_name
153 }
else if (doc_module != module_name && doc_module_conflict ==
"") {
154 doc_module_conflict = module_name
158function add_doc_line(line, content, meta, namespace_name, module_directive) {
159 content = strip_doc_marker(line)
160 doc_lines[++doc_count] = content
164 if (meta ~ /^@file([ \t]|$)/) {
165 if (doc_kind ==
"") {
168 }
else if (meta ~ /^@
namespace[ \t]+/) {
169 namespace_name = parse_doc_symbol(meta,
"@namespace")
170 if (doc_namespace != "" && doc_namespace != namespace_name) {
171 doc_namespace_conflict = namespace_name
173 doc_namespace = namespace_name
175 }
else if (meta ~ /^@module([ \t]|$)/) {
176 module_directive =
"@module"
177 record_module_directive(meta, module_directive)
178 }
else if (meta ~ /^@package([ \t]|$)/) {
179 module_directive =
"@package"
180 record_module_directive(meta, module_directive)
181 }
else if (meta ~ /^@fn[ \t]+/) {
183 doc_name = parse_doc_symbol(meta,
"@fn")
184 }
else if (meta ~ /^@var[ \t]+/) {
186 doc_name = parse_doc_symbol(meta,
"@var")
187 }
else if (is_param_directive(meta)) {
189 param_names[param_count] = parse_param_name(meta)
190 param_doc_lines[param_count] = doc_count
194function parse_doc_symbol(meta, directive, s) {
196 sub(
"^" directive
"[ \t]+",
"", s)
198 sub(/[ \t].*$/,
"", s)
203function parse_param_name(meta, s) {
205 sub(/^@param(\[(in|out|in,out)\])?[ \t]+/,
"", s)
207 sub(/[ \t].*$/,
"", s)
211function sanitize_identifier(name, fallback, s) {
213 gsub(/^[.][.][.]/,
"", s)
218 gsub(/[^A-Za-z0-9_:]/,
"_", s)
230function unique_param_name(name, base, n) {
233 while (param_seen[name]) {
241function prepare_param_names( i, clean) {
243 delete emitted_param_names
245 for (i = 1; i <= param_count; i++) {
246 clean = sanitize_identifier(param_names[i],
"arg")
247 emitted_param_names[i] = unique_param_name(clean)
251function rewrite_param_name(line, old_name, new_name, pos, tail, name_pos) {
252 pos = index(line,
"@param")
257 tail = substr(line, pos + 6)
258 if (!match(tail, /^(\[(in|out|in,out)\])?[ \t]+/)) {
262 name_pos = RLENGTH + 1
263 return substr(line, 1, pos + 5) \
264 substr(tail, 1, name_pos - 1) \
266 substr(tail, name_pos + length(old_name))
269function rewrite_param_doc_lines( i, line_number) {
270 for (i = 1; i <= param_count; i++) {
271 line_number = param_doc_lines[i]
272 doc_lines[line_number] = rewrite_param_name(doc_lines[line_number], param_names[i], emitted_param_names[i])
276function build_param_list( i, joined) {
279 for (i = 1; i <= param_count; i++) {
283 joined = joined
"String " emitted_param_names[i]
289function emit_doc_block(extra_line, suppress_fn, suppress_module, structural_line, trailing_line, suppress_var, i, line, meta) {
291 if (structural_line !=
"") {
292 print
" * " structural_line
294 for (i = 1; i <= doc_count; i++) {
297 if (suppress_fn && (meta ~ /^@fn([ \t]|$)/ || meta ~ /^@
namespace([ \t]|$)/)) {
300 if (suppress_module && (meta ~ /^@module([ \t]|$)/ || meta ~ /^@package([ \t]|$)/)) {
303 if (suppress_var && meta ~ /^@var([ \t]|$)/) {
312 if (trailing_line !=
"") {
313 print
" * " trailing_line
315 if (extra_line !=
"") {
316 print
" * " extra_line
321function normalize_func_decl(line, s) {
326 if (s ~ /^function[ \t]+/) {
327 sub(/^function[ \t]+/,
"", s)
330 sub(/[ \t]*\{[ \t;]*$/,
"", s)
332 sub(/[ \t]*\(\)[ \t]*$/,
"", s)
335 if (s ~ /^[A-Za-z_][A-Za-z0-9_:]*$/) {
342function is_probable_function_decl(line) {
343 return (normalize_func_decl(line) !=
"") && \
344 (line ~ /^[ \t]*(function[ \t]+)?[A-Za-z_][A-Za-z0-9_:]*[ \t]*(\(\))?[ \t]*(\{|$)/)
347function is_valid_identifier(name) {
348 return (name ~ /^[A-Za-z_][A-Za-z0-9_]*$/)
351function is_valid_namespace_path(path, parts, count, i) {
356 count = split(path, parts,
"::")
357 for (i = 1; i <= count; i++) {
358 if (!is_valid_identifier(parts[i])) {
366function split_qualified_identity(identity, info, parts, count, i, namespace_name) {
369 if (index(identity,
"::") == 0) {
373 count = split(identity, parts,
"::")
378 for (i = 1; i <= count; i++) {
379 if (!is_valid_identifier(parts[i])) {
384 namespace_name = parts[1]
385 for (i = 2; i < count; i++) {
386 namespace_name = namespace_name
"::" parts[i]
389 info[
"namespace"] = namespace_name
390 info[
"member"] = parts[count]
394function resolve_module_name( invalid) {
397 if (!doc_module_seen) {
401 if (doc_module_malformed !=
"") {
402 fail_or_warn(
"malformed " doc_module_malformed
" directive")
405 if (doc_module_invalid !=
"") {
406 fail_or_warn(
"invalid module identifier " doc_module_invalid)
409 if (doc_module_conflict !=
"") {
410 fail_or_warn(
"module metadata conflicts: " doc_module
" and " doc_module_conflict)
420function resolve_function_identity(physical_name, info, literal_info, documented_info, resolved_info, literal_qualified, documented_qualified, doc_has_qualification, valid_namespace, combined, identity, function_doc_name) {
423 function_doc_name = (doc_kind ==
"fn" ? doc_name :
"")
424 literal_qualified = split_qualified_identity(physical_name, literal_info)
425 doc_has_qualification = (function_doc_name !=
"" && index(function_doc_name,
"::") > 0)
426 documented_qualified = 0
429 if (doc_namespace_conflict !=
"") {
430 fail_or_warn(
"multiple @namespace directives conflict: " doc_namespace
" and " doc_namespace_conflict)
433 if (doc_namespace !=
"") {
434 if (is_valid_namespace_path(doc_namespace)) {
435 valid_namespace = doc_namespace
437 fail_or_warn(
"invalid @namespace path " doc_namespace)
441 if (doc_has_qualification) {
442 if (split_qualified_identity(function_doc_name, documented_info)) {
443 documented_qualified = 1
445 fail_or_warn(
"invalid qualified @fn identity " function_doc_name)
449 if (literal_qualified) {
450 identity = physical_name
452 if (documented_qualified && function_doc_name != physical_name) {
453 fail_or_warn(
"documentation identity " function_doc_name
" conflicts with literal Bash declaration " physical_name)
456 if (valid_namespace !=
"" && valid_namespace != literal_info[
"namespace"]) {
457 fail_or_warn(
"@namespace " valid_namespace
" conflicts with literal Bash namespace " literal_info[
"namespace"])
460 if (function_doc_name !=
"" && !doc_has_qualification) {
461 if (valid_namespace !=
"") {
462 combined = valid_namespace
"::" function_doc_name
463 if (combined != physical_name) {
464 fail_or_warn(
"documentation identity " combined
" conflicts with literal Bash declaration " physical_name)
466 }
else if (function_doc_name != physical_name) {
467 fail_or_warn(
"@fn documents " function_doc_name
" but declaration is " physical_name)
470 }
else if (documented_qualified) {
471 identity = function_doc_name
473 if (valid_namespace !=
"" && valid_namespace != documented_info[
"namespace"]) {
474 fail_or_warn(
"@namespace " valid_namespace
" conflicts with qualified @fn namespace " documented_info[
"namespace"])
476 }
else if (valid_namespace !=
"") {
477 if (function_doc_name ==
"") {
478 fail_or_warn(
"@namespace requires @fn for an unqualified Bash declaration")
479 identity = physical_name
480 } else if (doc_has_qualification) {
481 identity = physical_name
483 identity = valid_namespace
"::" function_doc_name
486 identity = physical_name
487 if (doc_namespace ==
"" && function_doc_name !=
"" && !doc_has_qualification && function_doc_name != physical_name) {
488 fail_or_warn(
"@fn documents " function_doc_name
" but declaration is " physical_name)
492 info[
"identity"] = identity
493 if (split_qualified_identity(identity, resolved_info)) {
494 info[
"namespace"] = resolved_info[
"namespace"]
495 info[
"member"] = resolved_info[
"member"]
497 info[
"namespace"] =
""
498 info[
"member"] = identity
502function emit_function(namespace_name, member_name, module_name, module_requested, params, namespace_parts, namespace_count, i, group_line) {
503 prepare_param_names()
504 rewrite_param_doc_lines()
505 params = build_param_list()
508 if (module_name != "") {
509 group_line =
"@ingroup " module_name
513 if (namespace_name !=
"") {
514 namespace_count = split(namespace_name, namespace_parts,
"::")
515 for (i = 1; i <= namespace_count; i++) {
516 print
"namespace " namespace_parts[i]
" {"
520 emit_doc_block(
"", 1, module_requested, group_line)
521 print
"int " member_name
"(" params
");"
523 for (i = namespace_count; i >= 1; i--) {
528function count_top_level_words(s, i, ch, quote, escaped, paren_depth, brace_depth, bracket_depth, in_word, count) {
537 for (i = 1; i <= length(s); i++) {
547 if (quote !=
"'" && ch ==
"\\") {
549 }
else if (ch == quote) {
561 if (ch ==
"'" || ch ==
"\"" || ch ==
"`") {
571 if (ch ==
")" && paren_depth > 0) {
581 if (ch ==
"}" && brace_depth > 0) {
591 if (ch ==
"]" && bracket_depth > 0) {
597 if ((ch ==
" " || ch ==
"\t") && paren_depth == 0 && brace_depth == 0 && bracket_depth == 0) {
615function classify_variable(raw_line, info, line, opts, name, value, eqpos, token) {
621 info[
"storage"] =
"global"
622 info[
"readonly"] =
"no"
623 info[
"exported"] =
"no"
624 info[
"declared"] =
"no"
625 info[
"explicit"] =
"no"
626 info[
"unsupported"] =
""
627 info[
"array"] =
"scalar"
628 info[
"integer"] =
"no"
629 info[
"nameref"] =
"no"
630 info[
"case_transform"] =
"none"
632 info[
"type"] =
"string"
634 if (line ~ /^local([ \t]|$)/) {
635 info[
"storage"] =
"local"
636 info[
"declared"] =
"yes"
637 info[
"explicit"] =
"yes"
638 sub(/^local[ \t]+/,
"", line)
639 }
else if (line ~ /^readonly([ \t]|$)/) {
640 info[
"readonly"] =
"yes"
641 info[
"declared"] =
"yes"
642 info[
"explicit"] =
"yes"
643 sub(/^readonly[ \t]+/,
"", line)
644 }
else if (line ~ /^export([ \t]|$)/) {
645 info[
"exported"] =
"yes"
646 info[
"declared"] =
"yes"
647 info[
"explicit"] =
"yes"
648 sub(/^export[ \t]+/,
"", line)
649 }
else if (line ~ /^(declare|typeset)([ \t]|$)/) {
650 info[
"declared"] =
"yes"
651 info[
"explicit"] =
"yes"
652 sub(/^(declare|typeset)[ \t]+/,
"", line)
655 while (line ~ /^-[A-Za-z]+([ \t]|$)/) {
657 sub(/[ \t].*$/,
"", token)
658 opts = substr(token, 2)
660 if (index(opts, "r")) info["readonly"] = "yes"
661 if (index(opts, "x")) info["exported"] = "yes"
662 if (index(opts, "a")) info["array"] = "indexed_array"
663 if (index(opts, "A")) info["array"] = "associative_array"
664 if (index(opts, "i")) info["integer"] = "yes"
665 if (index(opts, "n")) info["nameref"] = "yes"
666 if (index(opts, "l")) info["case_transform"] = "lowercase"
667 if (index(opts, "u")) info["case_transform"] = "uppercase"
669 sub(/^-[A-Za-z]+[ \t]*/, "", line)
677 if (info[
"explicit"] ==
"yes" && count_top_level_words(line) > 1) {
678 info[
"unsupported"] =
"multi_name"
682 eqpos = index(line,
"=")
684 name = trim(substr(line, 1, eqpos - 1))
685 value = trim(substr(line, eqpos + 1))
687 if (info[
"declared"] !=
"yes") {
694 sub(/[ \t].*$/,
"", name)
695 sub(/^[-+][A-Za-z]+[ \t]+/,
"", name)
697 if (name !~ /^[A-Za-z_][A-Za-z0-9_]*$/) {
701 if (info[
"array"] ==
"scalar" && value ~ /^\(/) {
702 info[
"array"] =
"indexed_array"
705 if (info[
"array"] ==
"associative_array") {
706 info[
"type"] =
"associative_array"
707 }
else if (info[
"array"] ==
"indexed_array") {
708 info[
"type"] =
"indexed_array"
709 }
else if (info[
"nameref"] ==
"yes") {
710 info[
"type"] =
"nameref"
711 }
else if (info[
"integer"] ==
"yes") {
712 info[
"type"] =
"integer"
714 info[
"type"] =
"string"
721function variable_meta(info, meta) {
722 meta =
"@details Bash variable: "
724 if (info[
"storage"] ==
"local") {
727 if (info[
"exported"] ==
"yes") {
728 meta = meta
"exported "
730 if (info[
"readonly"] ==
"yes") {
731 meta = meta
"readonly "
733 meta = meta
"read-write "
736 meta = meta info[
"type"]
738 if (info[
"case_transform"] ==
"lowercase") {
739 meta = meta
" lowercase-transform"
740 }
else if (info[
"case_transform"] ==
"uppercase") {
741 meta = meta
" uppercase-transform"
747function variable_pseudo_type(info, type) {
750 if (info[
"storage"] ==
"local") type = type
"Local"
751 if (info[
"exported"] ==
"yes") type = type
"Exported"
752 if (info[
"readonly"] ==
"yes") type = type
"Readonly"
754 if (info[
"type"] ==
"associative_array") {
755 type = type
"AssociativeArray"
756 }
else if (info[
"type"] ==
"indexed_array") {
757 type = type
"IndexedArray"
758 }
else if (info[
"type"] ==
"nameref") {
759 type = type
"NameReference"
760 }
else if (info[
"type"] ==
"integer") {
761 type = type
"Integer"
769function emit_variable(info, module_name, module_requested, type, group_line) {
771 if (module_name !=
"") {
772 group_line =
"@ingroup " module_name
774 emit_doc_block(variable_meta(info), 0, module_requested, group_line,
"", (group_line !=
""))
775 type = variable_pseudo_type(info)
776 print type " " info["name"] ";"
779function docs_are_file_only() {
780 return (doc_count > 0 && doc_kind ==
"file")
783function docs_are_module_definition() {
784 return (doc_count > 0 && doc_module_seen && doc_kind ==
"" && doc_namespace ==
"" && param_count == 0)
787function emit_module_definition( module_name) {
788 module_name = resolve_module_name()
789 if (module_name != "") {
790 emit_doc_block(
"", 0, 1,
"@defgroup " module_name
" " module_name)
792 emit_doc_block(
"@warning Invalid module metadata prevented group definition.", 0, 1,
"")
796function flush_file_docs_if_needed() {
797 if (docs_are_file_only()) {
805function flush_module_docs_if_needed() {
806 if (docs_are_module_definition()) {
807 emit_module_definition()
814function flush_unmatched_docs(reason) {
816 if (doc_module_seen) {
817 resolve_module_name()
822 emit_doc_block(
"@warning No recognized Bash declaration was associated with this documentation block.", 0, doc_module_seen,
"")
830 if (is_doc_line(source_line)) {
831 add_doc_line(source_line)
836 if (is_blank(source_line)) {
837 if (flush_file_docs_if_needed()) {
841 if (flush_module_docs_if_needed()) {
847 if (flush_file_docs_if_needed()) {
851 if (doc_count > 0 && is_transparent_annotation(source_line)) {
856 if (doc_count > 0 && docs_are_module_definition()) {
857 if (is_probable_function_decl(source_line)) {
858 fail_or_warn(
"module membership for function requires @fn")
859 emit_doc_block("@warning Module metadata was not associated because explicit @fn metadata is required.", 0, 1, "")
864 module_variable_status = classify_variable(source_line, module_var_info)
865 if (module_variable_status != 0) {
866 fail_or_warn(
"module membership for variable requires @var")
867 emit_doc_block("@warning Module metadata was not associated because explicit @var metadata is required.", 0, 1, "")
868 delete module_var_info
872 delete module_var_info
874 emit_module_definition()
880 if (doc_count > 0 && is_probable_function_decl(source_line)) {
881 fn_name = normalize_func_decl(source_line)
882 if (doc_kind ==
"var") {
883 fail_or_warn(
"@var block precedes function declaration " fn_name)
886 resolved_module_name =
""
887 if (doc_module_seen) {
888 resolved_module_name = resolve_module_name()
889 if (doc_kind != "fn") {
890 fail_or_warn(
"module membership for function requires @fn")
891 resolved_module_name = ""
895 resolve_function_identity(fn_name, fn_identity)
896 emit_function(fn_identity["namespace"], fn_identity["member"], resolved_module_name, doc_module_seen)
903 variable_status = classify_variable(source_line, var_info)
905 if (variable_status < 0 && var_info[
"unsupported"] ==
"multi_name") {
906 fail_or_warn(
"documented multi-name variable declarations are unsupported")
907 emit_doc_block("@warning Multiple Bash variable names in one declaration are outside the supported association model.")
913 if (variable_status > 0) {
914 resolved_module_name =
""
915 if (doc_module_seen) {
916 resolved_module_name = resolve_module_name()
917 if (doc_kind != "var") {
918 fail_or_warn(
"module membership for variable requires @var")
919 resolved_module_name = ""
922 if (doc_namespace != "") {
923 fail_or_warn(
"@namespace is only supported for function documentation")
925 if (doc_kind ==
"fn") {
926 fail_or_warn(
"@fn block precedes variable declaration " var_info[
"name"])
928 if (doc_name !=
"" && doc_name != var_info[
"name"]) {
929 fail_or_warn(
"@var documents " doc_name
" but declaration is " var_info[
"name"])
931 emit_variable(var_info, resolved_module_name, doc_module_seen)
940 flush_unmatched_docs("documentation block was not followed by a recognized declaration")
948 if (!flush_module_docs_if_needed()) {
949 flush_unmatched_docs(
"documentation block reached end of file without a declaration")
953 if (strict && (warning_count > 0 || error_count > 0)) {