native.starlark_doc_extract will not emit code for private symbols.
- Dominant language
- Java
- Stars
- 25.8k
- Forks
- 4.6k
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 72
Description
### Description of the bug:
The specification of the rule says that you do not specify symbol_names you get all public symbols. That is fine. It also says that if you specify some symbols, you get those.
But... the actual behavior is that if you specify a private symbol (e.g. "_license") you don't get doc data for that.
The reason for having this is that many rules come with a private core implementation and a public wrapper. It used to be possible to generate stardoc output for the private symbol and post process the result to give it the public name. This is much preferred over documenting the wrapper macro because the rule docs have richer semantics, showing the arg types, for example.
### Which category does this issue belong to?
_No response_
### What's the simplest, easiest way to reproduce this bug? Please provide a minimal example if possible.
foo.bzl
```
_foo = rule(doc = "i am foo", attrs = {...})
def foo(name, ...):
_foo(name=name, ...)
```
Or take a look at a real setup of the above concept. https://github.com/bazelbuild/rules_license/blob/main/doc_build/BUILD
git clone bazelbuild/rules_license
cd rules_license
bazel build //doc_build:reference.md
examing bazel-bin/doc_build/reference.md for the "good" definition of "license"
### What is the output of `bazel info release`?
release 7.1.2
Contributor guide
Research direction
Reproduce the issue with rules_license by running `bazel build //doc_build:reference.md` and inspect `bazel-bin/doc_build/reference.md`, comparing the public and private definitions in `doc_build/BUILD` and `foo.bzl`. Trace `native.starlark_doc_extract` to determine why explicitly requested private symbols are omitted; done means private-symbol documentation is emitted with the expected details.
Written by the indexing model from the issue text.
Assessment
- Domain
- build-system, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100