bazelbuild / bazelbuild/stardoc

Improve argument type strings for compound types and macro args

Open
#34 6 comments 1 reaction 0 assignees View on GitHub
P4 type: feature request
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.