search

bazelbuild / stardoc

Stardoc: Starlark Documentation Generator
Apache License 2.0
107 stars 42 forks source link

Improve argument type strings for compound types and macro args #34

Open trevorade opened 7 years ago

trevorade commented 7 years ago

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 commented 7 years ago

+cc @fweikert @laurentlb @dslomov @damienmg

c-parsons commented 5 years ago

This is probably something we want to address in Stardoc.

ComputerDruid commented 5 years ago

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 commented 5 years ago

PEP 484 looks like the best choice, indeed.

dgoldstein0 commented 3 years ago

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 commented 3 years ago

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