Add Documentation to Rules Emitted by bazel info build-language

[abhillman]

Description of the feature request:

Add documentation to the result of bazel info build-language

What underlying problem are you trying to solve with this feature?

bazel info build-language is relied upon by the IntelliJ plugin (i.e. see https://github.com/bazelbuild/intellij/blob/master/base/src/com/google/idea/blaze/base/lang/buildfile/sync/BuildLangSyncPlugin.java#L125 -- this runs bazel info build-language and then parses the output).

Because bazel info build-language does not emit documentation, all that is displayed for a given internal rule is the following (which is generated by the plugin and is the same for every built-in rule):

By adding documentation to the rules emitted, better documentation can be displayed for IntelliJ bazel users.

[abhillman]

Looks like key code was marked deprecated 6 years ago, even though it is a key part of the IntelliJ plugin. I think perhaps as a part of this fix, the @deprecated annotations could be removed.

Commit from 6 years ago: f07b76e#diff-a9d20b275e47b3ac9bdf13c11289270428ec0db8f69e9e1f1dee80909cedd4c2R568

@deprecated annotation from current releases:

bazel/src/main/java/com/google/devtools/build/lib/runtime/commands/info/BuildLanguageInfoItem.java

Line 47 in 33f7648

* Info item for the build language. It is deprecated, it still works, when explicitly requested,

[abhillman]

Related issues from the bazel intellij plugin repo

bazelbuild/intellij#3730
bazelbuild/intellij#3702

[abhillman]

Would be interested in implementing, pending some kind of green light.

Sketch of the design:

• update RuleClass and RuleClass.Builder to allow for specification and fetching of documentation (e.g. builder.setDocumentation(String doc), getDocumenation method on RuleClass)
• update RuleDefinition to have an overridable getDocumentation method that returns null by default
• refactor RuleClass documented attribute into a method isDocumented that checks if getDocumentation returns not null OR not empty string
• update BuildLanguageInfoItem to execute rulePb.setDocumentation.setDocumentation(ruleClass.getDocumentation()) in getBuildLanguageDefinition
• update RuleDefinition interface to have a String documentation() method
• update all rules that utilize the RuleDefinition interface to implement RuleDefinition

Do something similar for attributes (note that protos for rules/attributes already have a documentation field)

Tests:

• write a test called InfoCommandTest.java that lives in src/test/java/com/google/devtools/build/lib/runtime/commands
• write a test that walks over every rule/attr declared in src/main/java/com/google/devtools/build/lib/bazel/rules/BUILD and ensure that the programmatic documentation string matches inline documentation e.g. /*<!-- #BLAZE_RULE (NAME = java_binary, TYPE = BINARY, FAMILY = Java) -->

Also, probably remove @deprecated annotations because of its use by the IntelliJ plugin #15817 (comment)

[abhillman]

cc/ @ckolli5 -- hoping you might be able to weigh in or cc/ someone else

[fmeum]

The author of f07b76e, @lfpino, is still active and may be able to provide more context for the deprecation.

[meisterT]

I am wondering how useful this is when more and more rules are moving to Starlark.

cc @comius @brandjon

[lfpino]

I don't recall making InfoItem deprecated, also as @meisterT signals, this is for native rules only. Not sure if I can be of much help here. I refactored InfoItem to be able to inject the product name so that "Bazel" would be printed in the right places but I don't recall anything related to build-language.

[comius]

Some of the rules will remain in Bazel, so adding more info for native rules shouldn't hurt.

[github-actions]

Thank you for contributing to the Bazel repository! This issue has been marked as stale since it has not had any activity in the last 1+ years. It will be closed in the next 90 days unless any other activity occurs. If you think this issue is still relevant and should stay open, please post any comment here and the issue will no longer be marked as stale.

[tetromino]

Note that add245c added info for Starlarkified @_builtins rules to bazel info build-language output.