xref: /aosp_15_r20/external/stardoc/docs/writing_stardoc.md (revision b2fa42943c124aa9c7163734493fc7a7559681cf) 
1<nav class="toc">
2  <h2>Contents</h2>
3  <ul>
4    <li><a href="#rule-documentation">Rule Documentation</a></li>
5    <li><a href="#provider-documentation">Provider Documentation</a></li>
6    <li><a href="#macro-documentation">Macro / Function Documentation</a></li>
7  </ul>
8</nav>
9
10When generating documentation, Stardoc parses the `.bzl` file to extract the
11inline documentation as well as evaluates the Starlark code to determine the
12types for rule attributes. Stardoc will, by default, generate documentation for
13all rules, macros, and functions reachable from a target `.bzl` file.
14See [Generating Stardoc](generating_stardoc.md) for details on limiting the
15symbols for which stardoc generates documentation.
16
17<a name="rule-documentation"></a>
18## Rule Documentation
19
20When generating documentation, Stardoc parses the `.bzl` file to extract the
21inline documentation as well as evaluates the Starlark code to determine the
22types for rule attributes.
23
24Private rule attributes (attributes with names that begin with `_`) will not
25appear in generated documentation.
26
27[Starlark Rules](https://bazel.build/docs/skylark/rules.html) are declared using
28the `rule()` function as global variables.
29
30General rule documentation should be supplied in the `doc` parameter of the
31`rule()` function.
32
33Likewise, supply attribute documentation in the `doc` parameter of attribute
34schema-defining functions, such as `attr.label()`.
35
36```python
37my_rule = rule(
38    implementation = _my_rule_impl,
39    doc = """
40Example rule documentation.
41
42Example:
43  Here is an example of how to use this rule.
44""",
45    attrs = {
46        "srcs" : attr.label_list(
47            doc = "Source files used to build this target.",
48        ),
49        "deps" : attr.label_list(
50            doc = "Dependencies for this target.",
51        ),
52    }
53)
54```
55
56The `name` attribute that is common to all rules is documented by default.
57
58<a name="provider-documentation"></a>
59## Provider Documentation
60
61[Starlark Providers](https://docs.bazel.build/versions/master/skylark/rules.html#providers)
62are documented similarly to rules: using docstrings specified as parameters during
63creation of the provider.
64
65General provider documentation can be specified using the `doc` parameter
66to the `provider()` function.
67
68Field-related documentation can be specified by passing a map to the
69`fields` parameter of the `provider()` function. Keys are required field
70names, and values are their corresponding docstrings.
71
72```python
73MyInfo = provider(
74    doc = """
75A provider with some really neat documentation.
76
77Contains information about some of my favorite things.
78""",
79    fields = {'favorite_food' : 'A string representing my favorite food',
80              'favorite_color' : 'A string representing my favorite color'}
81)
82```
83
84<a name="macro-documentation"></a>
85## Macro / Function Documentation
86
87Functions and [Starlark Macros](https://bazel.build/docs/skylark/macros.html) are documented
88using docstrings similar to Python docstring format:
89
90```python
91def rat_check(name, srcs=[], format, visibility):
92  """Runs Apache Rat license checks on the given source files.
93
94  This rule runs [Apache Rat](http://creadur.apache.org/rat/) license checks on
95  a given set of source files. Use `bazel build` to run the check.
96
97  Args:
98    name: A unique name for this rule.
99    srcs: Source files to run the Rat license checks against.
100
101      Note that the Bazel glob() function can be used to specify which source
102      files to include and which to exclude.
103    format: The format to write the Rat check report in.
104    visibility: The visibility of this rule.
105  """
106  if format not in ['text', 'html', 'xml']:
107    fail('Invalid format: %s' % format, 'format')
108
109  _rat_check(
110      name = name,
111      srcs = srcs,
112      format = format,
113      visibility = visibility,
114  )
115```
116
117Parameters are documented in a special `Args:` section. Begin the documentation
118for each parameter on an indented line with the parameter name followed by a
119colon `:`. The documentation for a parameter can span multiple lines as long as
120each line is indented from the first line.
121
122
123