bazelbuild / bazelbuild/stardoc
Add types in the parameter table when generating function document with Stardoc
- Dominant language
- Java
- Stars
- 118
- Forks
- 51
- PR merge metrics
- No merged PRs in 30d
Description
We are trying to use Stardoc when generating documentation for our Bazel macros. I can get a table generated with parameter descriptions when follow the instruction here: [Macro/Function documentation](https://github.com/bazelbuild/stardoc/blob/master/docs/writing_stardoc.md#macro--function-documentation)
But we would also like to add the parameter `Type` in the table.
According to [DocstringUtils.java](https://github.com/bazelbuild/bazel/blob/2a4c6e335cbfe43d973b6804798002250a8e806d/src/tools/starlark/java/com/google/devtools/starlark/common/DocstringUtils.java) it seems like we shall write the `Type` in parentheses after the parameter name but before colon, as this example:
```
another_parameter (unused, mutable): a parameter may be followed by additional attributes in parenthese
```
I have seen that it's possible to add a rule template to the `stardoc()` rule (attribute: `func_template`). I started to use an own copy of the default template to play around with: //stardoc:templates/markdown_tables/func.vm
If I have understood correctly it doesn't seem that the attributes that I add in paranthese is fetched. And I don't think that I will be able to retreive that information by just updating the template. So I think that it will need an update in the Stardoc code for this, correct?! Is that something that is already planned? If I'm not correct then I would appreciate information how I can retreive the value of the attribute.
Thanks!
Contributor guide
Research direction
Start with the parameter parsing described in Bazel's DocstringUtils.java and Stardoc's //stardoc:templates/markdown_tables/func.vm template. Trace how parenthesized attributes reach the generated function table, then verify the generated documentation includes each parameter's type without losing existing descriptions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100