Improve doc string for `actions.run()` `arguments` argument
- 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
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