bazelbuild / bazelbuild/bazel

Improve doc string for `actions.run()` `arguments` argument

Open
#19,320 0 comments 0 reactions 0 assignees View on GitHub
team-Documentation team-Starlark-Integration type: documentation (cleanup) untriaged
Dominant language
Java
Stars
25.8k
Forks
4.6k
Avg merge
2d 20h
Merged PRs (30d)
72

Description

### Page link:

https://bazel-docs-staging.netlify.app/versions/master/skylark/lib/actions.html#run

### Problem description (include actual vs expected text, if applicable):

The `arguments` argument to `actions.run()` says:

> Must be a list of strings or [actions.args()](https://bazel-docs-staging.netlify.app/versions/master/skylark/lib/actions#args) objects.

This confused me for a solid 20 minutes cause I'm not the brightest bulb. I read it as a 'list of strings' or an 'args' object.. while off course it actually means 'a list' of 'strings or args objects'... Maybe it can be disambiguated to:

> Must be a list of strings or a list of [actions.args()](https://bazel-docs-staging.netlify.app/versions/master/skylark/lib/actions#args) objects.

### Where do you see this issue? (include link to specific section of the page, if applicable)

The `arguments` argument in the docs right [here](https://bazel-docs-staging.netlify.app/versions/master/skylark/lib/actions#run). The actual doc string in the code is [here](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java#L580).

### Any other information you'd like to share?

_No response_

Contributor guide

Open the contributing guide

Research direction

Open src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java at the documented arguments entry for actions.run(). Read the current wording and compare it with the linked staging documentation. Done means the text clearly describes a list containing strings or actions.args() objects and the generated documentation reflects that wording.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.