Extract documentation for named constants

[thomasvl]

Since feature flags are used by rules to enable behaviors (sanitizers, etc.), and they can be used globals with a bazel command line or via the common features rule attribute.

Generally, the features are just string values. Some projects use a constant in their bzl so they can ensure the same value is used in all cases the impls need it. That pattern generally works to provide a basis extracting the information into documentation. rules_swift is an example of this: https://github.com/bazelbuild/rules_swift/blob/master/swift/internal/features.bzl#L17-L115

So it would be nice if there was some way to scrap the string values and descriptions to make a page.

[thomasvl]

Possible straw man –

Make them more like rules/aspects:

SWIFT_FEATURE_COVERAGE = define_feature(
    name = "swift.coverage",
    doc = """
This feature is enabled if coverage collection is enabled for the build. (See the note above
about not depending on the C++ features.)
""",
)

Then at normal bazel runtime, SWIFT_FEATURE_COVERAGE just gets the value swift.coverage (and the existing Starlark just works), but StarDoc could extract the name and docs to then use for generate documentation.

Sincebazel doesn't really need define_feature and adding it just to generate docs might be questionable; it make sense to consider adding a macro in SkyLib/StarDoc that does this, but teach StarDoc to special case it during eval to exact the extra data.

[brandjon]

Interesting request.

I think the ideal solution is to let the author write the documentation in a way that keeps the source file as readable as possible. If that means parsing comments that appear adjacent to an assignment statement, I'd be ok with modifying Bazel to parse that information and make it available to Stardoc, though I think it'd require some changes to Starlark's parser and AST first.

But we don't necessarily want to just grab any comment that happens to appear next to a value, lest we accidentally capture an implementation detail or an unrelated comment. I think Python extends the triple-quoted docstring convention to apply to fields as well as functions, so maybe there's prior art to be borrowed here. String literals are unlikely to appear by themselves in a statement unless they're there for documentation.