bazelbuild / bazelbuild/stardoc
Example section no longer recognized in docstrings
- Dominant language
- Java
- Stars
- 118
- Forks
- 51
- PR merge metrics
- No merged PRs in 30d
Description
Skydoc recognizes special sections in docstrings such as `Args:` and `Example:`. Stardoc still recognizes `Args:` but no longer recognizes `Example:`. Given the following docstring:
```bzl
def some_function(name, arg):
"""This is some function.
Example:
Here is an example:
```bzl
foo = some_function("name", "arg")
```
Args:
name: The name.
arg: The argument.
"""
```
I would expect output containing markdown along the lines of
### Examples
Here is an example:
```bzl
foo = some_function("name", "arg")
```
### Attributes
...
However, Stardoc no longer generates a section (or a proto entry) for examples.
We have several such examples in the `rules_haskell` documentation ([source](https://github.com/tweag/rules_haskell/blob/v0.11/haskell/defs.bzl#L348), [rendered](https://release.api.haskell.build/haskell/defs.html#haskell_toolchain_library_examples)).
A workaround is to use level 3 headings (`###`) in the docstring directly. However, this makes the `Example` and `Args` sections inconsistent in the source docstring.
I did not compare other special sections, e.g. `Returns:`. However, looking at the [proto](https://github.com/bazelbuild/stardoc/blob/master/stardoc/proto/stardoc_output.proto) it seems that `Args:` is the only section that Stardoc recognizes.
How should users migrating from Skydoc to Stardoc handle such sections? Could support for further sections be added to Stardoc?
Contributor guide
Research direction
Start with stardoc/proto/stardoc_output.proto and the section handling for Args:, then trace how recognized docstring sections reach generated Markdown. Compare the supplied Example docstring with the expected output. Done means example content is represented in the proto and rendered as an Examples section, with coverage for the shown input.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100