Reference Docs in Source Code#

In your C++/Rust/Python source code, you want to reference requirements (needs). The docs-as-code tool will create backlinks in the documentation in two steps:

You add a special comment in your source code that references the need ID.
Scan for those comments and provide needs links to your documentation.

For an example result, look at the attribute source_code_link of Enforces title wording rules (tool_req__docs_common_attr_title).

Comments in Source Code#

Use a comment and start with req-Id: or req-traceability: followed by the need ID.

# req-Id: TOOL_REQ__EXAMPLE_ID
# req-traceability: TOOL_REQ__EXAMPLE_ID

For other languages (C++, Rust, etc.), use the appropriate comment syntax.

Scanning Source Code for Links#

In your BUILD files, pass the implementation targets to the docs rule as code_targets. Their srcs, hdrs, and textual_hdrs are scanned, including those of their deps recursively within the component boundary described below. This means that a cc_executable also covers source files from the cc_library targets it uses. You may also pass filegroups; their files are scanned directly.

Source-link scanning includes the sources and headers of every explicitly selected target, even when it is outside the bundle package. Transitive dependencies are filtered by the repository and BUILD package containing the docs_bundle declaration; subpackage targets are included. Local targets reached through a sibling package or external repository are included too. This boundary does not depend on source_dir. Source and header attributes resolve filegroups and generated outputs; selecting generator rules directly as implementation targets is not supported.

cc_library(
   name = "some_library",
   srcs = [
       "bar.cpp",
   ],
)

cc_executable(
   name = "some_application",
   srcs = ["main.cpp"],
   deps = [":some_library"],
)

docs(
   external_needs = [
      "@score_process_description//:docs",
   ],
   source_dir = "docs",
   code_targets = [":some_application"],
   primary_need_id = "comp__some_component",
)

primary_need_id is optional and identifies the single Need representing the bundle’s primary subject. A bundle can contain many other Needs; target metadata is attached only to this explicitly selected Need. The ID is never derived from the Bazel bundle name.