Add recommendations for documenting Starlark APIs#320
Conversation
Formalize the basics of what e.g. Stardoc expects from .bzl files.
| ``` | ||
|
|
||
| If both the leading and trailing doc comment is specified, the trailing doc | ||
| comment takes precedence. |
There was a problem hiding this comment.
Is that Sphinx behavior? Seems error prone -- the special #: notation combined with the requirement that there be no intervening lines is a pretty clear signal that both comments are intended as documentation, so I don't see the utility of not failing fast.
I'd consider this to be in the same category as double-documenting the same variable at two different assignments (usually only possible in the local case, since standard Starlark dialect bans global reassignment).
There was a problem hiding this comment.
Yes, preferring the trailing comment is Sphinx behavior.
I suppose I should omit the statement about precedence entirely, since this is a recommendation doc - and users should not do that.
| 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 |
There was a problem hiding this comment.
"first line of" -> "first statement of" (allows for intervening comments and whitespace)
| 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 |
There was a problem hiding this comment.
Clarify that applications and organizations may specify additional best practices (for readers who might otherwise take this doc as definitive for google3 or for .bzl).
|
|
||
| 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 |
There was a problem hiding this comment.
"uninterrupted" -- is it clear that there can't be a blank line between the comment and assignment statement?
#: doesn't work
x =1
#: but this does
#:
y = 2There was a problem hiding this comment.
Also, a non-trailing comment must not trail some other statement, as in
pass #: stuff about x
x = 1(Verify that's consistent with sphinx.)
| 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: |
There was a problem hiding this comment.
Do we need to specify anything about what happens to a doc comment that cannot be associated with any variable/assignment? I.e., floating free, or in the degenerate but valid assignments:
[] = []
() = ()My guess is it's fine to not say anything specific.
There was a problem hiding this comment.
On the other hand, we could make it fail-fast on docgen. But that sounds annoying for commenting out variable declarations, like how Go requires you to update imports during experimental debugging edits. And it's not like the doc comment would accidentally apply to a different var when the first one is commented out.
| ``` | ||
|
|
||
| If both the leading and trailing doc comment is specified, the trailing doc | ||
| comment takes precedence. |
There was a problem hiding this comment.
Update for offline discussion wherein we said it's illegal to specify a doc comment twice for the same var, including cases where global variable reassignment is allowed (not standard but permissible in some implementations), and in the case where there's both a preceding and trailing doc comment.
"illegal" in this context means for doc purposes, not rejecting the program at the parser/evaluator level (or else it should be in spec.md).
Also, since you apply doc comments to all LHS vars, you may have this issue in the form
#: doc for x and y
x, y = ...
#: doc for y and z
y, z = ...But only when reassignment of y is allowed.
There was a problem hiding this comment.
Clarified. I don't think it's worth specifically mentioning multiple assignment - just say that a documentation processor is allowed to error out if it sees multiple doc comments on the same variable.
There was a problem hiding this comment.
"allowed to error out" -- and if it doesn't, it might take only the first, or only the last, or concatenate them? If that's the case, it's basically "unspecified behavior". Which might be alright, since this shouldn't come up in practice.
2 participants
Formalize the basics of what e.g. Stardoc expects from .bzl files.
Working towards bazelbuild/stardoc#202