search

bazelbuild / stardoc

Stardoc: Starlark Documentation Generator
Apache License 2.0
107 stars 42 forks source link

Allow marking non-private rule attributes as undocumented or hidden #223

Open tetromino opened 4 months ago

tetromino commented 4 months ago

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.

tetromino commented 4 months ago

Probably option 1b is the easiest way to go, since it is self-explanatory at the rule declaration point and doesn't require coordinating stardoc and bazel releases.

I'm wondering if there is any prior art for such a magic "do not use this" docstring value - maybe something in the python world?