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.