bazelbuild / bazelbuild/stardoc
Allow marking non-private rule attributes as undocumented or hidden
- Dominant language
- Java
- Stars
- 118
- Forks
- 51
- PR merge metrics
- No merged PRs in 30d
Description
From @fenghaolw in https://github.com/bazelbuild/stardoc/pull/46:
> In our cases (inside of Google) it is quite a common to have "public" attribute for migration but really do not want anyone to use. We use scary names like "xxx_for_migration_only_please_do_not_use_without_talking_with_us". Printing this in stardoc is annoying.
I think this is a reasonable feature to have. I can see several ways of fixing this:
1. in Bazel native code: add a mechanism for attributes to be marked as undocumented or hidden:
a. via a new parameter to attribute constructors: `xxx_for_migration_only = attr.label(undocumented = True)`; or
b. via a magic value for `doc`: `xxx_for_migration_only = attr.label(doc = "__undocumented__")`
2. in Bazel native code: add a mechanism for `starlark_doc_extract` to hide documentation for some attributes, maybe something like `starlark_doc_extract(name = "foo_doc", src = "//:foo.bzl", hide_attributes = {"rule_foo": ["xxx_for_migration_only"]})`
3. in Stardoc: same as above, with the filtering performed in the renderer when reading the proto.
I would lean to option 1 or 3.
Contributor guide
Research direction
Review the three proposed approaches: attribute constructors in Bazel, starlark_doc_extract filtering, and Stardoc renderer filtering while reading the proto. No implementation files or tests are named, so first determine which repository component owns attribute visibility and documentation rendering. Done means non-private rule attributes can be marked undocumented or hidden and the generated Stardoc output omits them.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100