bazelbuild / bazelbuild/stardoc

Add types in the parameter table when generating function document with Stardoc

Open
#73 0 comments 1 reaction 0 assignees View on GitHub
P4 type: feature request
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.