Stardoc for targets

[cmcgee1024]

Sometimes the target's name and rule kind don't provide much detail on its purpose. When should the target be used? Is it runnable, testable, or just buildable? Maybe it's meant only to be used as part of a larger dependency?

This kind of information along with details that come from the rule could be a good source of documentation for a package, especially for newcomers. Imagine looking through a BUILD.bazel file with a bunch of sh_binary() targets. This could seem very opaque without some context.

[cmcgee1024]

I'm not sure what form this should take or if this should be part of bazel itself instead of just the stardoc tool.

For example, if rules themselves all had an optional doc attribute, then the documentation could be queried interactively using bazel query. The stardoc tool could then pull this information and the rule information to assemble documentation for the entire package, which can be pulled into a larger document generation system.

[brandjon]

I can see documentation for targets making sense, particularly for config_settings and build_settings, and maybe for toolchains too. We'd have to decide on a syntax, expose it through bazel, and update stardoc to consume it.

[aiuto]

+1 to doing this for config_setting. It is the first step in being able to retain documentation for flags that migrate from native bazel to starlark.