bazelbuild
Add conveniences to easily document the public interface while the implementation is private.
A common use case is:
- //my/rules:foo.bzl, the public interface to
foo() - //my/rules/private:foo.bzl: actually defines
foo() - //my/rules/docs/BUILD has a set of stardoc rules to make a comprehensive doc set for a suite of rules.
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.
This sounds like a specific application for #27 (documentation inheritance)
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
