bazelbuild / bazelbuild/stardoc

Allow marking non-private rule attributes as undocumented or hidden

Open
#223 1 comment 1 reaction 0 assignees View on GitHub
P3 type: feature request
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.