Add conveniences to easily document the public interface while the implementation is private. #120
Labels
Comments
aiuto
added a commit
to aiuto/rules_pkg
that referenced
this issue
Feb 8, 2022
where the rules are defined. Without that, you just have to know. It would be nice if stardoc had support for adding the bzl path out of the box. bazelbuild/stardoc#120
|
This sounds like a specific application for #27 (documentation inheritance) |
aiuto
added a commit
to bazelbuild/rules_pkg
that referenced
this issue
Feb 16, 2022
…es (#530) where the rules are defined. Without that, you just have to know. It would be nice if stardoc had support for adding the bzl path out of the box. bazelbuild/stardoc#120
aiuto
added a commit
to bazelbuild/rules_pkg
that referenced
this issue
Feb 16, 2022
* Try to make the docs a little better. - Fix stardoc adding <p align=center> in markdown tables. - Add rough capability to handle macros that wrap a rule. The wrapping technique is: - In the wrapping macro, use the docstring @wraps(some_rule) - Then we don't emit the docs for the wrapper - In the docs for some_rule, replace the string "some_rule" with the name of the wrapper macro. It is a first attempt to make things better. It is crude, but it mostly works.It is a first attempt to make things better. It is crude, but it mostly works. If Stardoc ever adds this capability [(feature request)[bazelbuild/stardoc#120] we can move to that.
|
In Aspect's rules, we solve this by just documenting the public interface, and omit docstrings from the private implementation to avoid duplicating them in both places. This works fine when the private implementation is truly not usable by end-users, so they'll never notice absent docstrings. Yes, it's a pity that the docs don't go directly on the attributes, but in practice it's not difficult. When the underlying rule could be used by users, see my comment on #98 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
A common use case is:
foo()foo()The final docs should say that
foo()is defined in//my/rules:foo.bzl%foo, and not mention private. The documentation for that should come from the definition at//my/rules/private:foo.bzl.It would be handy if the renderer could splice in
//my/rules:foo.bzl%based on the public declaration.The text was updated successfully, but these errors were encountered: