bazelbuild / bazelbuild/bazel

Stardoc protos and ModuleInfoExtractor / starlark_doc_extract should export parameter type annotations for builtin functions

Open
#21,979 2 comments 13 reactions 1 assignee Claimed by @tetromino View on GitHub
P2 team-Starlark-Integration type: feature request
Dominant language
Java
Stars
25.8k
Forks
4.6k
Avg merge
2d 20h
Merged PRs (30d)
72

Description

If we want to documenting builtin functions using ModuleInfoExtractor / starlark_doc_extract (e.g. for the BUILD language API pages of the build encyclopedia), we need to support annotations for parameter types - since builtin functions (unlike ordinary Starlark-defined functions) have them.

The proto representation of type annotations we pick needs to be flexible enough for future needs - there is community pressure to add type annotations to ordinary Starlark-defined functions too.

Two reasonable possibilities are

* flat string - this is what src/main/protobuf/builtin.proto does; maximally flexible, but requires the consumer to do parse the string
* tree of nodes - easier to parse for a consumer, but more of a maintenance burden for us (since new types will inevitably appear and will need to be supported)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.