bazelbuild / bazelbuild/bazel

native.starlark_doc_extract will not emit code for private symbols.

Closed
#23,513 0 comments 0 reactions 0 assignees View on GitHub
team-Loading-API type: bug untriaged
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.