bash-doxygen
Reference documentation for bash-doxygen
Loading...
Searching...
No Matches
doxygen-bash.awk
1#!/usr/bin/awk -f
2#
3# doxygen-bash-docfilter.awk
4#
5# Documentation-led Doxygen preprocessor for Bash, implemented as a single
6# portable awk file.
7#
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
11# variation.
12#
13# Supported primary comment style:
14# ## @brief ...
15# ## @details
16# ## ...
17#
18# Supported documented declarations include:
19# name() {
20# name () {
21# function name() {
22# function name {
23# namespace::name() {
24# readonly NAME=value
25# readonly NAME
26# declare -r NAME=value
27# declare -a NAME=(...)
28# declare -A NAME=(...)
29# declare NAME
30# typeset NAME
31# export NAME=value
32# export NAME
33# local NAME=value
34# local NAME
35# NAME=value
36# NAME=(...)
37#
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.
40
41BEGIN {
42 strict = (strict ? strict : 0)
43 keep_blanks = (compact ? 0 : 1)
44
45 for (arg_index = 1; arg_index < ARGC; arg_index++) {
46 if (ARGV[arg_index] == "--strict") {
47 strict = 1
48 ARGV[arg_index] = ""
49 } else if (ARGV[arg_index] == "--compact") {
50 keep_blanks = 0
51 ARGV[arg_index] = ""
52 }
53 }
54
55 reset_doc()
56}
57
58function reset_doc() {
59 doc_count = 0
60 doc_kind = ""
61 doc_name = ""
62 doc_namespace = ""
63 doc_namespace_conflict = ""
64 doc_module = ""
65 doc_module_conflict = ""
66 doc_module_invalid = ""
67 doc_module_malformed = ""
68 doc_module_seen = 0
69 param_count = 0
70 delete doc_lines
71 delete param_names
72 delete param_doc_lines
73 delete emitted_param_names
74}
75
76function trim(s) {
77 sub(/^[ \t\r\n]+/, "", s)
78 sub(/[ \t\r\n]+$/, "", s)
79 return s
80}
81
82function emit_blank() {
83 if (keep_blanks) {
84 print ""
85 }
86}
87
88function warn(message) {
89 print FILENAME ":" FNR ": warning: " message > "/dev/stderr"
90 warning_count++
91}
92
93function fail_or_warn(message) {
94 warn(message)
95 if (strict) {
96 error_count++
97 }
98}
99
100function is_blank(line) {
101 return (line ~ /^[ \t]*$/)
102}
103
104function is_doc_line(line) {
105 return (line ~ /^[ \t]*##([ \t]|$)/)
106}
107
108function is_transparent_annotation(line, s) {
109 s = trim(line)
110 return (s ~ /^#[ \t]*shellcheck[ \t]+disable=SC[0-9]+([ \t]*,[ \t]*SC[0-9]+)*[ \t]*$/)
111}
112
113function strip_doc_marker(line, s) {
114 s = line
115 sub(/^[ \t]*##[ \t]?/, "", s)
116 return s
117}
118
119function is_param_directive(meta) {
120 return (meta ~ /^@param(\[(in|out|in,out)\])?[ \t]+/)
121}
122
123function record_module_directive(meta, directive, s, module_name) {
124 doc_module_seen = 1
125 s = meta
126 sub("^" directive, "", s)
127
128 if (s !~ /^[ \t]+/) {
129 if (doc_module_malformed == "") {
130 doc_module_malformed = directive
131 }
132 return
133 }
134
135 s = trim(s)
136 if (s == "" || s ~ /[ \t]/) {
137 if (doc_module_malformed == "") {
138 doc_module_malformed = directive
139 }
140 return
141 }
142
143 module_name = s
144 if (!is_valid_identifier(module_name)) {
145 if (doc_module_invalid == "") {
146 doc_module_invalid = module_name
147 }
148 return
149 }
150
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
155 }
156}
157
158function add_doc_line(line, content, meta, namespace_name, module_directive) {
159 content = strip_doc_marker(line)
160 doc_lines[++doc_count] = content
161
162 meta = trim(content)
163
164 if (meta ~ /^@file([ \t]|$)/) {
165 if (doc_kind == "") {
166 doc_kind = "file"
167 }
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
172 } else {
173 doc_namespace = namespace_name
174 }
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]+/) {
182 doc_kind = "fn"
183 doc_name = parse_doc_symbol(meta, "@fn")
184 } else if (meta ~ /^@var[ \t]+/) {
185 doc_kind = "var"
186 doc_name = parse_doc_symbol(meta, "@var")
187 } else if (is_param_directive(meta)) {
188 param_count++
189 param_names[param_count] = parse_param_name(meta)
190 param_doc_lines[param_count] = doc_count
191 }
192}
193
194function parse_doc_symbol(meta, directive, s) {
195 s = meta
196 sub("^" directive "[ \t]+", "", s)
197 s = trim(s)
198 sub(/[ \t].*$/, "", s)
199 sub(/\(.*$/, "", s)
200 return s
201}
202
203function parse_param_name(meta, s) {
204 s = meta
205 sub(/^@param(\[(in|out|in,out)\])?[ \t]+/, "", s)
206 s = trim(s)
207 sub(/[ \t].*$/, "", s)
208 return s
209}
210
211function sanitize_identifier(name, fallback, s) {
212 s = name
213 gsub(/^[.][.][.]/, "", s)
214 gsub(/^--/, "", s)
215 gsub(/\[\]$/, "", s)
216 gsub(/[=]$/, "", s)
217 gsub(/-/, "_", s)
218 gsub(/[^A-Za-z0-9_:]/, "_", s)
219
220 if (s == "") {
221 s = fallback
222 }
223 if (s ~ /^[0-9]/) {
224 s = "p_" s
225 }
226
227 return s
228}
229
230function unique_param_name(name, base, n) {
231 base = name
232 n = 1
233 while (param_seen[name]) {
234 n++
235 name = base "_" n
236 }
237 param_seen[name] = 1
238 return name
239}
240
241function prepare_param_names( i, clean) {
242 delete param_seen
243 delete emitted_param_names
244
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)
248 }
249}
250
251function rewrite_param_name(line, old_name, new_name, pos, tail, name_pos) {
252 pos = index(line, "@param")
253 if (pos == 0) {
254 return line
255 }
256
257 tail = substr(line, pos + 6)
258 if (!match(tail, /^(\[(in|out|in,out)\])?[ \t]+/)) {
259 return line
260 }
261
262 name_pos = RLENGTH + 1
263 return substr(line, 1, pos + 5) \
264 substr(tail, 1, name_pos - 1) \
265 new_name \
266 substr(tail, name_pos + length(old_name))
267}
268
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])
273 }
274}
275
276function build_param_list( i, joined) {
277 joined = ""
278
279 for (i = 1; i <= param_count; i++) {
280 if (joined != "") {
281 joined = joined ", "
282 }
283 joined = joined "String " emitted_param_names[i]
284 }
285
286 return joined
287}
288
289function emit_doc_block(extra_line, suppress_fn, suppress_module, structural_line, trailing_line, suppress_var, i, line, meta) {
290 print "/**"
291 if (structural_line != "") {
292 print " * " structural_line
293 }
294 for (i = 1; i <= doc_count; i++) {
295 line = doc_lines[i]
296 meta = trim(line)
297 if (suppress_fn && (meta ~ /^@fn([ \t]|$)/ || meta ~ /^@namespace([ \t]|$)/)) {
298 continue
299 }
300 if (suppress_module && (meta ~ /^@module([ \t]|$)/ || meta ~ /^@package([ \t]|$)/)) {
301 continue
302 }
303 if (suppress_var && meta ~ /^@var([ \t]|$)/) {
304 continue
305 }
306 if (line == "") {
307 print " *"
308 } else {
309 print " * " line
310 }
311 }
312 if (trailing_line != "") {
313 print " * " trailing_line
314 }
315 if (extra_line != "") {
316 print " * " extra_line
317 }
318 print " */"
319}
320
321function normalize_func_decl(line, s) {
322 s = line
323 sub(/#.*/, "", s)
324 s = trim(s)
325
326 if (s ~ /^function[ \t]+/) {
327 sub(/^function[ \t]+/, "", s)
328 }
329
330 sub(/[ \t]*\{[ \t;]*$/, "", s)
331 s = trim(s)
332 sub(/[ \t]*\(\)[ \t]*$/, "", s)
333 s = trim(s)
334
335 if (s ~ /^[A-Za-z_][A-Za-z0-9_:]*$/) {
336 return s
337 }
338
339 return ""
340}
341
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]*(\{|$)/)
345}
346
347function is_valid_identifier(name) {
348 return (name ~ /^[A-Za-z_][A-Za-z0-9_]*$/)
349}
350
351function is_valid_namespace_path(path, parts, count, i) {
352 if (path == "") {
353 return 0
354 }
355
356 count = split(path, parts, "::")
357 for (i = 1; i <= count; i++) {
358 if (!is_valid_identifier(parts[i])) {
359 return 0
360 }
361 }
362
363 return 1
364}
365
366function split_qualified_identity(identity, info, parts, count, i, namespace_name) {
367 delete info
368
369 if (index(identity, "::") == 0) {
370 return 0
371 }
372
373 count = split(identity, parts, "::")
374 if (count < 2) {
375 return 0
376 }
377
378 for (i = 1; i <= count; i++) {
379 if (!is_valid_identifier(parts[i])) {
380 return 0
381 }
382 }
383
384 namespace_name = parts[1]
385 for (i = 2; i < count; i++) {
386 namespace_name = namespace_name "::" parts[i]
387 }
388
389 info["namespace"] = namespace_name
390 info["member"] = parts[count]
391 return 1
392}
393
394function resolve_module_name( invalid) {
395 invalid = 0
396
397 if (!doc_module_seen) {
398 return ""
399 }
400
401 if (doc_module_malformed != "") {
402 fail_or_warn("malformed " doc_module_malformed " directive")
403 invalid = 1
404 }
405 if (doc_module_invalid != "") {
406 fail_or_warn("invalid module identifier " doc_module_invalid)
407 invalid = 1
408 }
409 if (doc_module_conflict != "") {
410 fail_or_warn("module metadata conflicts: " doc_module " and " doc_module_conflict)
411 invalid = 1
412 }
413
414 if (invalid) {
415 return ""
416 }
417 return doc_module
418}
419
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) {
421 delete info
422
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
427 valid_namespace = ""
428
429 if (doc_namespace_conflict != "") {
430 fail_or_warn("multiple @namespace directives conflict: " doc_namespace " and " doc_namespace_conflict)
431 }
432
433 if (doc_namespace != "") {
434 if (is_valid_namespace_path(doc_namespace)) {
435 valid_namespace = doc_namespace
436 } else {
437 fail_or_warn("invalid @namespace path " doc_namespace)
438 }
439 }
440
441 if (doc_has_qualification) {
442 if (split_qualified_identity(function_doc_name, documented_info)) {
443 documented_qualified = 1
444 } else {
445 fail_or_warn("invalid qualified @fn identity " function_doc_name)
446 }
447 }
448
449 if (literal_qualified) {
450 identity = physical_name
451
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)
454 }
455
456 if (valid_namespace != "" && valid_namespace != literal_info["namespace"]) {
457 fail_or_warn("@namespace " valid_namespace " conflicts with literal Bash namespace " literal_info["namespace"])
458 }
459
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)
465 }
466 } else if (function_doc_name != physical_name) {
467 fail_or_warn("@fn documents " function_doc_name " but declaration is " physical_name)
468 }
469 }
470 } else if (documented_qualified) {
471 identity = function_doc_name
472
473 if (valid_namespace != "" && valid_namespace != documented_info["namespace"]) {
474 fail_or_warn("@namespace " valid_namespace " conflicts with qualified @fn namespace " documented_info["namespace"])
475 }
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
482 } else {
483 identity = valid_namespace "::" function_doc_name
484 }
485 } else {
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)
489 }
490 }
491
492 info["identity"] = identity
493 if (split_qualified_identity(identity, resolved_info)) {
494 info["namespace"] = resolved_info["namespace"]
495 info["member"] = resolved_info["member"]
496 } else {
497 info["namespace"] = ""
498 info["member"] = identity
499 }
500}
501
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()
506
507 group_line = ""
508 if (module_name != "") {
509 group_line = "@ingroup " module_name
510 }
511
512 namespace_count = 0
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] " {"
517 }
518 }
519
520 emit_doc_block("", 1, module_requested, group_line)
521 print "int " member_name "(" params ");"
522
523 for (i = namespace_count; i >= 1; i--) {
524 print "}"
525 }
526}
527
528function count_top_level_words(s, i, ch, quote, escaped, paren_depth, brace_depth, bracket_depth, in_word, count) {
529 quote = ""
530 escaped = 0
531 paren_depth = 0
532 brace_depth = 0
533 bracket_depth = 0
534 in_word = 0
535 count = 0
536
537 for (i = 1; i <= length(s); i++) {
538 ch = substr(s, i, 1)
539
540 if (escaped) {
541 escaped = 0
542 in_word = 1
543 continue
544 }
545
546 if (quote != "") {
547 if (quote != "'" && ch == "\\") {
548 escaped = 1
549 } else if (ch == quote) {
550 quote = ""
551 }
552 in_word = 1
553 continue
554 }
555
556 if (ch == "\\") {
557 escaped = 1
558 in_word = 1
559 continue
560 }
561 if (ch == "'" || ch == "\"" || ch == "`") {
562 quote = ch
563 in_word = 1
564 continue
565 }
566 if (ch == "(") {
567 paren_depth++
568 in_word = 1
569 continue
570 }
571 if (ch == ")" && paren_depth > 0) {
572 paren_depth--
573 in_word = 1
574 continue
575 }
576 if (ch == "{") {
577 brace_depth++
578 in_word = 1
579 continue
580 }
581 if (ch == "}" && brace_depth > 0) {
582 brace_depth--
583 in_word = 1
584 continue
585 }
586 if (ch == "[") {
587 bracket_depth++
588 in_word = 1
589 continue
590 }
591 if (ch == "]" && bracket_depth > 0) {
592 bracket_depth--
593 in_word = 1
594 continue
595 }
596
597 if ((ch == " " || ch == "\t") && paren_depth == 0 && brace_depth == 0 && bracket_depth == 0) {
598 if (in_word) {
599 count++
600 in_word = 0
601 }
602 continue
603 }
604
605 in_word = 1
606 }
607
608 if (in_word) {
609 count++
610 }
611
612 return count
613}
614
615function classify_variable(raw_line, info, line, opts, name, value, eqpos, token) {
616 delete info
617 line = raw_line
618 sub(/#.*/, "", line)
619 line = trim(line)
620
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"
631 info["name"] = ""
632 info["type"] = "string"
633
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)
653 }
654
655 while (line ~ /^-[A-Za-z]+([ \t]|$)/) {
656 token = line
657 sub(/[ \t].*$/, "", token)
658 opts = substr(token, 2)
659
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"
668
669 sub(/^-[A-Za-z]+[ \t]*/, "", line)
670 line = trim(line)
671 }
672
673 if (line == "") {
674 return 0
675 }
676
677 if (info["explicit"] == "yes" && count_top_level_words(line) > 1) {
678 info["unsupported"] = "multi_name"
679 return -1
680 }
681
682 eqpos = index(line, "=")
683 if (eqpos > 0) {
684 name = trim(substr(line, 1, eqpos - 1))
685 value = trim(substr(line, eqpos + 1))
686 } else {
687 if (info["declared"] != "yes") {
688 return 0
689 }
690 name = line
691 value = ""
692 }
693
694 sub(/[ \t].*$/, "", name)
695 sub(/^[-+][A-Za-z]+[ \t]+/, "", name)
696
697 if (name !~ /^[A-Za-z_][A-Za-z0-9_]*$/) {
698 return 0
699 }
700
701 if (info["array"] == "scalar" && value ~ /^\(/) {
702 info["array"] = "indexed_array"
703 }
704
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"
713 } else {
714 info["type"] = "string"
715 }
716
717 info["name"] = name
718 return 1
719}
720
721function variable_meta(info, meta) {
722 meta = "@details Bash variable: "
723
724 if (info["storage"] == "local") {
725 meta = meta "local "
726 }
727 if (info["exported"] == "yes") {
728 meta = meta "exported "
729 }
730 if (info["readonly"] == "yes") {
731 meta = meta "readonly "
732 } else {
733 meta = meta "read-write "
734 }
735
736 meta = meta info["type"]
737
738 if (info["case_transform"] == "lowercase") {
739 meta = meta " lowercase-transform"
740 } else if (info["case_transform"] == "uppercase") {
741 meta = meta " uppercase-transform"
742 }
743
744 return meta
745}
746
747function variable_pseudo_type(info, type) {
748 type = ""
749
750 if (info["storage"] == "local") type = type "Local"
751 if (info["exported"] == "yes") type = type "Exported"
752 if (info["readonly"] == "yes") type = type "Readonly"
753
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"
762 } else {
763 type = type "String"
764 }
765
766 return type
767}
768
769function emit_variable(info, module_name, module_requested, type, group_line) {
770 group_line = ""
771 if (module_name != "") {
772 group_line = "@ingroup " module_name
773 }
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"] ";"
777}
778
779function docs_are_file_only() {
780 return (doc_count > 0 && doc_kind == "file")
781}
782
783function docs_are_module_definition() {
784 return (doc_count > 0 && doc_module_seen && doc_kind == "" && doc_namespace == "" && param_count == 0)
785}
786
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)
791 } else {
792 emit_doc_block("@warning Invalid module metadata prevented group definition.", 0, 1, "")
793 }
794}
795
796function flush_file_docs_if_needed() {
797 if (docs_are_file_only()) {
798 emit_doc_block("")
799 reset_doc()
800 return 1
801 }
802 return 0
803}
804
805function flush_module_docs_if_needed() {
806 if (docs_are_module_definition()) {
807 emit_module_definition()
808 reset_doc()
809 return 1
810 }
811 return 0
812}
813
814function flush_unmatched_docs(reason) {
815 if (doc_count > 0) {
816 if (doc_module_seen) {
817 resolve_module_name()
818 }
819 if (reason != "") {
820 fail_or_warn(reason)
821 }
822 emit_doc_block("@warning No recognized Bash declaration was associated with this documentation block.", 0, doc_module_seen, "")
823 reset_doc()
824 }
825}
826
827{
828 source_line = $0
829
830 if (is_doc_line(source_line)) {
831 add_doc_line(source_line)
832 next
833 }
834
835 if (doc_count > 0) {
836 if (is_blank(source_line)) {
837 if (flush_file_docs_if_needed()) {
838 emit_blank()
839 next
840 }
841 if (flush_module_docs_if_needed()) {
842 emit_blank()
843 }
844 next
845 }
846
847 if (flush_file_docs_if_needed()) {
848 emit_blank()
849 }
850
851 if (doc_count > 0 && is_transparent_annotation(source_line)) {
852 emit_blank()
853 next
854 }
855
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, "")
860 reset_doc()
861 next
862 }
863
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
869 reset_doc()
870 next
871 }
872 delete module_var_info
873
874 emit_module_definition()
875 reset_doc()
876 emit_blank()
877 next
878 }
879
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)
884 }
885
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 = ""
892 }
893 }
894
895 resolve_function_identity(fn_name, fn_identity)
896 emit_function(fn_identity["namespace"], fn_identity["member"], resolved_module_name, doc_module_seen)
897 delete fn_identity
898 reset_doc()
899 next
900 }
901
902 if (doc_count > 0) {
903 variable_status = classify_variable(source_line, var_info)
904
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.")
908 delete var_info
909 reset_doc()
910 next
911 }
912
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 = ""
920 }
921 }
922 if (doc_namespace != "") {
923 fail_or_warn("@namespace is only supported for function documentation")
924 }
925 if (doc_kind == "fn") {
926 fail_or_warn("@fn block precedes variable declaration " var_info["name"])
927 }
928 if (doc_name != "" && doc_name != var_info["name"]) {
929 fail_or_warn("@var documents " doc_name " but declaration is " var_info["name"])
930 }
931 emit_variable(var_info, resolved_module_name, doc_module_seen)
932 delete var_info
933 reset_doc()
934 next
935 }
936
937 delete var_info
938 }
939
940 flush_unmatched_docs("documentation block was not followed by a recognized declaration")
941 }
942
943 emit_blank()
944}
945
946END {
947 if (doc_count > 0) {
948 if (!flush_module_docs_if_needed()) {
949 flush_unmatched_docs("documentation block reached end of file without a declaration")
950 }
951 }
952
953 if (strict && (warning_count > 0 || error_count > 0)) {
954 exit 1
955 }
956}