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

[tetromino]

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)

[hauserx]

I think having a tree of nodes with string identified generic types should allow to avoid maintenance burden - new types, or custom types (like depset) can be added without modifying proto. Below draft proposal. It still need to be cross validated with SEP-001 Bootstrapping Starlark types

// Sample:
//
// {
//     type_name: "dict",
//     generic_param_name: ["Key", "Value"]
//     method: [..., {name: "keys", return_type: {  type_name: "list", generic_param: {"Elem" : "Key"}  } }
// }
message TypeInfo {
    string type_name = 1; // e.g. "NoneType", "int", "dict", "depset"
    string doc_string = 2;
    repeated generic_param_name = 3; // e.g. "Key", "Value"
    bool supports_variadic_params = 3;  // True for list, tuple, sequence, etc.
    StarlarkFunctionInfo method = 4;
}

// Samples:
//
// {  type_name: "int" }
//
// Or:
//
// {
//     type_name: "dict",
//     generic_param: [ "Key": {"string"}, "Value": {"int"} ]
// }
//
// {
//     type_name: "tuple",
//     variadic_param: {type_name: "string"}
// }
message TypeReference {
    string type_name = 1;
    // Must have the same number of entries as TypeInfo with the corresponding type_name.
    // Making it recursive allows to express: dict[ string, list[int] ]
    map<string, TypeReference> generic_param = 2;
    TypeReference variadic_param = 3;
}

message TypeExpression {
    // Allows to express e.g "int | NoneType"
    repeated TypeReference alternatives = 1;
}

message FunctionParamInfo {
    // ...fields...

    TypeExpression type = 6;
}