bazelbuild / bazelbuild/stardoc

`symbol_names` is documented in a few places as only defaulting to `rule` entries

Open
#37 0 comments 0 reactions 0 assignees View on GitHub
P4 type: bug
Dominant language
Java
Stars
118
Forks
51
PR merge metrics
No merged PRs in 30d

Description

https://github.com/bazelbuild/stardoc/blob/master/docs/stardoc_rule.md#stardoc-symbol_names

https://github.com/bazelbuild/stardoc/blob/master/docs/generating_stardoc.md#single-file

Seem to say if nothing is provide for `symbol_names`, it defaults to only documenting the `rule` entries.

But https://github.com/bazelbuild/stardoc/blob/master/docs/writing_stardoc.md does say:

> Stardoc will, by default, generate documentation for all rules, macros, and functions reachable from a target `.bzl` file.

But then links over to the other doc which just talks about rules again.

https://github.com/bazelbuild/stardoc/blob/master/docs/writing_stardoc.md#rule-documentation also mentioned that attributes with a leading underscore (`_`) won't be documented, but nothing indicates if the default behavior for `symbol_names` will do something similar (skipping runes, macros, or providers that start with a underscore).

Contributor guide

Open the contributing guide

Research direction

Compare the `symbol_names` sections in `docs/stardoc_rule.md` and `docs/generating_stardoc.md` with `docs/writing_stardoc.md`. Check the documented default behavior for rules, macros, functions, providers, and leading-underscore symbols. Done when the affected documentation consistently describes the behavior and links do not contradict one another.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 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.