From 4fd19f703022b374a811c731b76b37d5df6abbec Mon Sep 17 00:00:00 2001 From: Alexandre Rostovtsev Date: Tue, 12 Aug 2025 14:43:54 -0400 Subject: [PATCH 1/5] Add recommendations for documenting Starlark APIs Formalize the basics of what e.g. Stardoc expects from .bzl files. --- README.md | 5 ++-- conventions.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+), 2 deletions(-) create mode 100644 conventions.md diff --git a/README.md b/README.md index 6db6c0d..8d8439e 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,9 @@ Starlark (formerly known as Skylark) is a language intended for use as a configuration language. It was designed for the [Bazel](https://bazel.build/) build system, but may be useful for other projects as well. This repository is where Starlark features are proposed, discussed, and specified. It contains -information about the language, including the [specification](spec.md). There -are [multiple implementations of Starlark](https://github.com/laurentlb/awesome-starlark). +information about the language, including the [specification](spec.md) and +[recommended conventions](conventions.md). There are [multiple implementations +of Starlark](https://github.com/laurentlb/awesome-starlark). Starlark is a dialect of [Python](https://www.python.org/). Like Python, it is a diff --git a/conventions.md b/conventions.md new file mode 100644 index 0000000..f32684e --- /dev/null +++ b/conventions.md @@ -0,0 +1,68 @@ +# Starlark Language Conventions + +This document describes non-normative but generally recommended conventions for +Starlark. + +## API Documentation + +### Docstrings + +API documentation for a function should be provided in a [Python-style +docstring](https://peps.python.org/pep-0257/) - a string literal which is the +first line of the function's body. + +By convention, this string should consist of an optional newline, followed by +a 1-line, 1-sentence summary, optionally followed by a blank line and blank-line +delimited paragraphs of additional documentation text. + +If a string literal is the first statement in a Starlark source file, it is +treated as the documentation for that file; the conventions are the same as for +a function's docstring. + +For example: + +```python +"""A collection of useful utilities""" + +def is_valid(config): + """ + Verifies if `config` is a valid configuration. + + Usage example: + + is_valid({"example": {"cpu": "arm"}}) # returns True + """ + ... +``` + +Documentation processors should take care to dedent common leading whitespace +from a multiline docstring's lines (note that the first line could have no +leading whitespace). + +### Doc comments + +API documentation for a constant may be provided in +[Sphinx-style](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#doc-comments-and-docstrings) +*doc comments*, which start with `#:` optionally followed by a space. + +An uninterrupted block of doc comments attaches to the identifier on the left +hand side of the immediately following assignment statement: + +```python +#: List of allowed configuration names +#: in an unspecified order +ALLOWED_CONFIGS = ["foo", "bar"] +``` + +Alternatively, a one-line trailing doc comment may be given inline after the end +of the right-hand side of an assignment statement: + +```python +DEFAULT_TAGS = { + "foo": [], + "bar": ["local", "manual"], +} #: Default list of tags for each configuration +``` + +If both the leading and trailing doc comment is specified, the trailing doc +comment takes precedence. From ad0b6c24b626d156fa304b8052a41622ed2edc17 Mon Sep 17 00:00:00 2001 From: Alexandre Rostovtsev Date: Tue, 12 Aug 2025 14:56:31 -0400 Subject: [PATCH 2/5] wording --- conventions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/conventions.md b/conventions.md index f32684e..4d1d52b 100644 --- a/conventions.md +++ b/conventions.md @@ -45,8 +45,8 @@ API documentation for a constant may be provided in [Sphinx-style](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#doc-comments-and-docstrings) *doc comments*, which start with `#:` optionally followed by a space. -An uninterrupted block of doc comments attaches to the identifier on the left -hand side of the immediately following assignment statement: +An uninterrupted block of doc comments attaches to the symbol on the left hand +side of the immediately following assignment statement: ```python #: List of allowed configuration names From bba70b02e6ab891864e8596d1b48bcc850d58c2a Mon Sep 17 00:00:00 2001 From: Alexandre Rostovtsev Date: Wed, 13 Aug 2025 15:50:14 -0400 Subject: [PATCH 3/5] Incorporate brandjon's suggestions --- conventions.md | 38 ++++++++++++++++++-------------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/conventions.md b/conventions.md index 4d1d52b..794fc72 100644 --- a/conventions.md +++ b/conventions.md @@ -7,22 +7,18 @@ Starlark. ### Docstrings -API documentation for a function should be provided in a [Python-style -docstring](https://peps.python.org/pep-0257/) - a string literal which is the -first line of the function's body. +API documentation for a Starlark module or function should be provided in a +*docstring* - a string literal which is the first line of the module or of the +function's body. By convention, this string should consist of an optional newline, followed by a 1-line, 1-sentence summary, optionally followed by a blank line and blank-line delimited paragraphs of additional documentation text. -If a string literal is the first statement in a Starlark source file, it is -treated as the documentation for that file; the conventions are the same as for -a function's docstring. - For example: ```python -"""A collection of useful utilities""" +"""A collection of useful utilities.""" def is_valid(config): """ @@ -35,23 +31,28 @@ def is_valid(config): ... ``` -Documentation processors should take care to dedent common leading whitespace -from a multiline docstring's lines (note that the first line could have no -leading whitespace). +No particular markup format for the text is prescribed, but Markdown and HTML +are commonly used in practice. Documentation processors - especially if +interpreting docstrings as Markdown-formatted - should take care to dedent +common leading whitespace from a multiline docstring's lines (note that the +first line could have no leading whitespace). ### Doc comments -API documentation for a constant may be provided in -[Sphinx-style](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#doc-comments-and-docstrings) -*doc comments*, which start with `#:` optionally followed by a space. +API documentation for a global variable may be provided in [Sphinx +autodoc-style](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#doc-comments-and-docstrings) +*doc comments*, which start with `#:` optionally followed by one space. -An uninterrupted block of doc comments attaches to the symbol on the left hand -side of the immediately following assignment statement: +An uninterrupted block of doc comments attaches to the symbol(s) on the left +hand side of the immediately following assignment statement: ```python #: List of allowed configuration names -#: in an unspecified order +#: in priority order ALLOWED_CONFIGS = ["foo", "bar"] + +#: Default foo map +FOO_MAP, _ = generate_foo_and_bar_maps() ``` Alternatively, a one-line trailing doc comment may be given inline after the end @@ -63,6 +64,3 @@ DEFAULT_TAGS = { "bar": ["local", "manual"], } #: Default list of tags for each configuration ``` - -If both the leading and trailing doc comment is specified, the trailing doc -comment takes precedence. From 64fc4d077fdb753f5f8aa841ce0d44d79378e330 Mon Sep 17 00:00:00 2001 From: Alexandre Rostovtsev Date: Thu, 14 Aug 2025 20:08:13 -0400 Subject: [PATCH 4/5] Further edit --- conventions.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/conventions.md b/conventions.md index 794fc72..3058976 100644 --- a/conventions.md +++ b/conventions.md @@ -8,8 +8,8 @@ Starlark. ### Docstrings API documentation for a Starlark module or function should be provided in a -*docstring* - a string literal which is the first line of the module or of the -function's body. +*docstring* - a string literal which is the first statement of the module or of +the function's body. By convention, this string should consist of an optional newline, followed by a 1-line, 1-sentence summary, optionally followed by a blank line and blank-line @@ -31,11 +31,14 @@ def is_valid(config): ... ``` -No particular markup format for the text is prescribed, but Markdown and HTML -are commonly used in practice. Documentation processors - especially if -interpreting docstrings as Markdown-formatted - should take care to dedent -common leading whitespace from a multiline docstring's lines (note that the -first line could have no leading whitespace). +No particular markup format for the text is prescribed; we observe that Markdown +and HTML are commonly used in practice. Of course, projects and organizations +can specify additional guidelines for their documentation formatting. + +Documentation processing tools - especially if interpreting docstrings as +Markdown-formatted - should take care to dedent common leading whitespace from a +multiline docstring's lines (note that the first line could have no leading +whitespace). ### Doc comments @@ -43,8 +46,10 @@ API documentation for a global variable may be provided in [Sphinx autodoc-style](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#doc-comments-and-docstrings) *doc comments*, which start with `#:` optionally followed by one space. -An uninterrupted block of doc comments attaches to the symbol(s) on the left -hand side of the immediately following assignment statement: +An uninterrupted sequence of one or more lines which contain *only* doc comments +(optionally preceded by whitespace before the `#:`) forms a *doc comment block*. +Such a doc comment block attaches to the symbol(s) on the left hand side of the +assignment statement that starts on the immediately following line: ```python #: List of allowed configuration names @@ -64,3 +69,8 @@ DEFAULT_TAGS = { "bar": ["local", "manual"], } #: Default list of tags for each configuration ``` + +Doc comments attach to variables, not to values. For example, if a global +variable whose value happens to be `True` has a doc comment, documentation +processing tools should take care not to attach the doc comment's text to +unrelated occurrences of `True` in other parts of the code. From 28d229d8484dc57259bffa285f29028570417755 Mon Sep 17 00:00:00 2001 From: Alexandre Rostovtsev Date: Thu, 14 Aug 2025 20:19:45 -0400 Subject: [PATCH 5/5] Further edit --- conventions.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/conventions.md b/conventions.md index 3058976..b0f368e 100644 --- a/conventions.md +++ b/conventions.md @@ -70,7 +70,11 @@ DEFAULT_TAGS = { } #: Default list of tags for each configuration ``` +Documentation processing tools may treat multiple doc comments attached to the +same variable as an error (for example, if a variable has both a preceding doc +comment block and a trailing in-line doc comment). + Doc comments attach to variables, not to values. For example, if a global variable whose value happens to be `True` has a doc comment, documentation -processing tools should take care not to attach the doc comment's text to -unrelated occurrences of `True` in other parts of the code. +processing tools shouldn't attach the doc comment's text to unrelated +occurrences of `True` in other parts of the code.