Skip to content

Latest commit

 

History

History
122 lines (96 loc) · 3.99 KB

writing_stardoc.md

File metadata and controls

122 lines (96 loc) · 3.99 KB
Raw

Contents

When generating documentation, Stardoc parses the .bzl file to extract the inline documentation as well as evaluates the Starlark code to determine the types for rule attributes. Stardoc will, by default, generate documentation for all rules, macros, and functions reachable from a target .bzl file. See Generating Stardoc for details on limiting the symbols for which stardoc generates documentation.

Rule Documentation

When generating documentation, Stardoc parses the .bzl file to extract the inline documentation as well as evaluates the Starlark code to determine the types for rule attributes.

Private rule attributes (attributes with names that begin with _) will not appear in generated documentation.

Starlark Rules are declared using the rule() function as global variables.

General rule documentation should be supplied in the doc parameter of the rule() function.

Likewise, supply attribute documentation in the doc parameter of attribute schema-defining functions, such as attr.label().

my_rule = rule(
    implementation = _my_rule_impl,
    doc = """
Example rule documentation.

Example:
  Here is an example of how to use this rule.
""",
    attrs = {
        "srcs" : attr.label_list(
            doc = "Source files used to build this target.",
        ),
        "deps" : attr.label_list(
            doc = "Dependencies for this target.",
        ),
    }
)

The name attribute that is common to all rules is documented by default.

Provider Documentation

Starlark Providers are documented similarly to rules: using docstrings specified as parameters during creation of the provider.

General provider documentation can be specified using the doc parameter to the provider() function.

Field-related documentation can be specified by passing a map to the fields parameter of the provider() function. Keys are required field names, and values are their corresponding docstrings.

MyInfo = provider(
    doc = """
A provider with some really neat documentation.

Contains information about some of my favorite things.
""",
    fields = {'favorite_food' : 'A string representing my favorite food',
              'favorite_color' : 'A string representing my favorite color'}
)

Macro / Function Documentation

Functions and Starlark Macros are documented using docstrings similar to Python docstring format:

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: 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: The format to write the Rat check report in.
    visibility: The visibility of this rule.
  """
  if format not in ['text', 'html', 'xml']:
    fail('Invalid format: %s' % format, 'format')

  _rat_check(
      name = name,
      srcs = srcs,
      format = format,
      visibility = visibility,
  )

Parameters are documented in a special Args: section. Begin the documentation for each parameter on an indented line with the parameter name followed by a colon :. The documentation for a parameter can span multiple lines as long as each line is indented from the first line.