Improve argument type strings for compound types and macro args

[trevorade]

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:

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

[davidzchen]

+cc @fweikert @laurentlb @dslomov @damienmg

[c-parsons]

This is probably something we want to address in Stardoc.

[ComputerDruid]

Instead of {List of String} I'd be much happier to see the typing syntax used for python: https://www.python.org/dev/peps/pep-0484/ . So that's be written as {List[str]} (assuming you still need the curly braces to tell what's a type specification)

[laurentlb]

PEP 484 looks like the best choice, indeed.

[dgoldstein0]

at a higher level - I would love if starlark itself adopted mypy-like typechecking. I've often struggled with getting the shape of providers right, and felt that static typing would better attribute the mistakes to where they are made in code when the types start getting complicated.

[alandonovan]

@dgoldstein0 See bazelbuild/starlark#106. But I don't see types remotely near the top of our priorities for the next 12 months.