|
bash-doxygen
Reference documentation for bash-doxygen
|
Accepted
This ADR defines how bash-doxygen represents namespace-oriented function identities while preserving the distinction between literal Bash symbol names and documentation-only structure.
The filter remains documentation-led. It SHALL preserve source evidence when a Bash function is literally qualified with ::, and it MAY introduce a separate Doxygen namespace identity only when the source documentation makes that abstraction explicit. It SHALL NOT infer namespaces from naming conventions such as config_load, network_http_get, or other prefixes.
This decision governs literal qualified Bash functions, qualified @fn directives, the new @namespace structural directive, conflict handling, nested namespace paths, and the pseudo-C++ representation emitted for Doxygen.
Bash does not provide a language-level namespace construct comparable to C++. Projects nevertheless use naming conventions to organize shell functions, and Bash permits function names that contain characters such as : when written in supported function declaration forms. bash-doxygen already recognizes function names containing colons because its documented-function classifier accepts names matching:
A function such as:
therefore contains direct source evidence that the Bash symbol itself is named config::load. Treating that form as documentation namespace structure does not require guessing from a naming convention; the source symbol already carries an explicit qualified identity.
A different use case is documentation abstraction. A project may have an implementation symbol such as:
while wishing the generated documentation to present that function as config::load. The filter cannot infer this safely from the config_ prefix. The same implementation name could equally mean a flat function called config_load, a private helper, or an unrelated convention.
Issue #19 therefore introduces explicit documentation namespace metadata:
The source now distinguishes two identities:
config_load; andconfig::load.This distinction must remain visible in the architecture. A documentation abstraction must not rewrite history by implying that Bash itself provides namespace semantics or that the physical symbol has a different runtime name.
The existing function pipeline also creates an important representation constraint. ADR-002 makes the synthesized pseudo-C++ declaration the sole emitted function signature, while source @fn metadata is consumed for validation and suppressed from the generated documentation block. Namespace support must extend that principle without reintroducing a second structural signature through @namespace.
ADR-004 adds a second requirement: the chosen pseudo-C++ representation must not be accepted merely because a golden file looks plausible. It must also survive the focused Bash-to-filter-to-Doxygen XML integration path and produce the intended namespace and function model in Doxygen.
network::http.For every documented function, the filter SHALL distinguish:
The physical Bash symbol remains the identity used for source association and for explaining runtime reality. The documentation identity controls the pseudo-C++ namespace and member name emitted for Doxygen.
The filter SHALL NOT mutate or reinterpret the physical symbol in source. It only chooses an indexing representation for Doxygen.
A documentation namespace path SHALL contain one or more identifier segments separated by exactly ::.
Each segment SHALL match:
Examples of valid namespace paths include:
Examples outside the supported namespace model include empty segments, leading or trailing ::, single-colon separators, or segments beginning with a digit. Unsupported explicit namespace metadata SHALL produce a diagnostic and SHALL fail under --strict according to the existing diagnostic contract.
This syntax rule applies to the namespace interpretation introduced by this ADR. It does not retroactively claim that every character sequence previously accepted by the broad Bash function-name recognizer is valid C++ namespace syntax.
A recognized Bash function declaration whose name is a valid qualified identity containing :: SHALL provide authoritative namespace evidence.
For example:
has:
No @namespace or @fn directive is required for the filter to preserve that literal qualification.
Nested literal names are supported when every segment is valid:
which maps to namespace path network::http and member get.
A qualified source @fn directive provides explicit documentation identity. For example:
requests documentation identity config::load while preserving physical Bash symbol config_load.
This is a deliberate exception to the ordinary unqualified @fn mismatch rule. A qualified @fn is not required to equal an unqualified physical declaration because its qualification explicitly requests a documentation abstraction.
When the physical Bash symbol is itself qualified, the qualified @fn SHALL agree with that literal identity. A mismatch SHALL produce a diagnostic rather than allowing documentation metadata to rename a literal qualified source symbol.
@namespace is a source-side structural directive. Its intended documentation abstraction is formed together with @fn.
For example:
requests documentation identity config::load.
The implementation symbol does not need to match load because the explicit namespace metadata establishes that documentation identity independently of the physical Bash name.
An explicit namespace may itself be nested:
which requests network::http::get.
@namespace without an accompanying @fn SHALL NOT invent a member name from an unqualified implementation symbol. Such a block lacks enough explicit evidence for a documentation-only remapping and SHALL produce a diagnostic. A literal qualified Bash declaration is the exception: when the declaration already provides a complete qualified identity, a matching @namespace may be used as redundant validation metadata even without @fn.
This rule avoids creating an implicit convention in which @namespace config automatically converts config_load or load into config::load.
Multiple explicit namespace sources MAY appear together when they agree.
This is valid:
The literal declaration, qualified @fn, and explicit @namespace all identify the same namespace path.
This is also valid:
because @namespace config plus unqualified @fn load() resolves to the same identity as the literal declaration.
Redundancy is treated as corroborating evidence rather than as an error.
Evidence may be considered in the following conceptual order when selecting a candidate identity:
@fn;@namespace plus unqualified @fn;This ordering SHALL NOT silently override contradictions.
Every explicit source that can be resolved to a namespace path or complete qualified identity SHALL be checked for agreement with the selected identity. Conflicts SHALL produce diagnostics and SHALL fail in strict mode.
For example:
is conflicting because the explicit namespace says config while the qualified @fn says network.
Likewise:
conflicts with the literal Bash symbol config::load.
The filter SHALL NOT "fix" either form by choosing whichever source has higher precedence and ignoring the other.
When no namespace abstraction is present, existing behavior remains in force.
For example:
is valid, while:
continues to produce the existing mismatch diagnostic.
An unqualified @fn therefore remains physical-symbol validation unless it is combined with explicit @namespace metadata.
For successfully recognized functions, source @fn and @namespace directives are structural input to the filter and SHALL NOT be emitted into the generated function documentation block.
This extends the principle established by ADR-002: the synthesized declaration and namespace structure are the sole Doxygen-facing structural representation. Descriptive commands such as @brief, @details, @param, @returns, and @retval remain attached to the synthesized member declaration.
Unmatched documentation blocks continue to preserve their source text according to the existing unmatched-documentation behavior; this ADR changes suppression only for successfully resolved functions.
A qualified documentation identity SHALL be emitted as nested C++ namespace blocks containing an unqualified synthesized function declaration.
For example, documentation identity:
shall be represented equivalently to:
The exact whitespace and line arrangement are filter-output details protected by regression fixtures. The architectural requirement is that Doxygen sees real namespace compounds and the documented function as a member of the innermost namespace.
Qualified declarations such as int network::http::get(...); outside namespace blocks were considered, but namespace blocks are preferred because they do not require a prior namespace/member declaration to be valid C++ structure and are more directly represented by Doxygen's namespace model.
The chosen representation SHALL be verified through the XML-only integration suite before the feature is considered complete.
The filter could map config_load to config::load or network_http_get to network::http::get automatically.
This was rejected because underscore naming does not carry an unambiguous namespace contract. Inference would create documentation structure from a convention the source never declared and would violate ADR-000's requirement for capability honesty and evidence-oriented behavior.
The filter could combine @namespace config with the following physical symbol and derive config::config_load or attempt to strip a prefix.
This was rejected because neither behavior is clearly implied by the source. For documentation-only remapping, @fn supplies the member identity explicitly.
Literal config::load functions or qualified @fn config::load() directives could be rejected unless a separate @namespace config is present.
This was rejected because those forms already contain explicit complete qualification. Requiring duplicate metadata would add ceremony without adding evidence.
The filter could always trust literal declarations over @fn, and qualified @fn over @namespace plus unqualified @fn.
This was rejected because contradictory documentation would remain in source and could mislead maintainers even if the generated output happened to be consistent. Conflicts are documentation defects and must remain visible.
The source @namespace line could be preserved and left for Doxygen to interpret.
This was rejected because it would create a second structural representation beside the synthesized namespace blocks and could cause the function comment to be interpreted as namespace documentation. Structural source metadata is consumed and translated instead.
The filter could continue emitting:
without namespace blocks.
This was rejected as the primary representation because qualified member function declarations outside their namespace generally rely on prior declarations and provide a weaker, less explicit Doxygen namespace model. The focused Doxygen integration test should validate actual namespace compounds.
The filter could attempt to discover namespace relationships from wrappers, associative tables, sourcing layout, prefixes, or other project conventions.
This was rejected as outside scope. Bash does not provide one language-level namespace construct for the filter to parse, and such inference would conflict with the bounded parser architecture established by ADR-000 and ADR-008.
Literal qualified Bash function names can be documented without losing their source identity.
Projects may create a documentation namespace abstraction for differently named implementation functions, but they must state that abstraction explicitly with a qualified @fn or with @namespace plus @fn.
Nested namespaces become a supported documentation structure rather than a flat string convention.
The function parser must retain additional per-block metadata: explicit namespace path, source @fn identity, physical declaration identity, and the resolved documentation identity.
The emitter must split qualified identities into namespace path and member name, emit nested namespace blocks, and suppress source @namespace structural lines for successfully recognized functions.
Namespace output necessarily introduces generated lines around a function relative to a flat declaration. Exact source-line preservation is therefore secondary to representing the documentation model correctly for this feature. The filter should avoid unnecessary expansion beyond the namespace structure required by Doxygen.
The focused Doxygen integration fixture gains namespace assertions so that future refactors cannot preserve a plausible golden pseudo-C++ file while silently breaking Doxygen's namespace/member model.
No namespace behavior is inferred for variables by this ADR. The decision is limited to documented Bash functions requested by issue #19. Variable namespacing, groups/modules, and class abstractions require separate decisions if introduced later.
Existing ordinary unqualified documented functions retain their current output and mismatch behavior.
Existing literal names containing valid :: qualification gain a stronger Doxygen representation: the generated function is placed inside corresponding namespace blocks rather than emitted as a flat qualified declaration.
A qualified @fn paired with an unqualified implementation symbol now becomes an explicit documentation abstraction instead of an ordinary name mismatch. This is an intentional feature expansion.
Source that contains contradictory explicit namespace evidence will now produce a diagnostic. Under strict mode this becomes a non-zero exit status, consistent with existing documentation-drift behavior.
Projects that currently rely on inferred underscore prefixes receive no new namespace behavior. They must opt in explicitly.
config::load functions appear as load within Doxygen namespace config;@fn config::load() can document a differently named Bash implementation without pretending the runtime symbol changed;@namespace config plus @fn load() produces the same documentation identity;