bazelbuild / bazelbuild/stardoc
Improve argument type strings for compound types and macro args
- Dominant language
- Java
- Stars
- 118
- Forks
- 51
- PR merge metrics
- No merged PRs in 30d
Description
Currently, with the exception of optional arguments and those named `name` or `deps` and perhaps a few more, all the types for Skylark macro arguments are `Unknown`.
I propose that skydoc support specifying argument types for macros using a {CurlyBrace} syntax. Here's an example:
```python
def rat_check(name, srcs=[], format, visibility):
"""Runs Apache Rat license checks on the given source files.
This rule runs [Apache Rat](http://creadur.apache.org/rat/) license checks on
a given set of source files. Use `bazel build` to run the check.
Args:
name: A unique name for this rule.
srcs: {List of Label} Source files to run the Rat license checks against.
Note that the Bazel glob() function can be used to specify which source
files to include and which to exclude.
format: {String} The format to write the Rat check report in.
visibility: {List of String} The visibility of this rule.
"""
```
Presumably, you'd have a handful of supported types as indicated by:
https://bazel.build/versions/master/docs/skylark/lib/skylark-builtin.html
Contributor guide
Research direction
Start with skydoc's handling of Skylark macro arguments and compare the proposed {CurlyBrace} syntax with the supported types in the linked Skylark built-in documentation. Done means documented compound and macro argument types are recognized and rendered instead of Unknown, including the List of Label and List of String examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, python
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100