doc strings: support documentation of the result

A complete documentation of a rule should not only include how to
use it (i.e., which fields are present and what is their meaning)
but also what the result is. This is particularly true, as the result
is structured and can contain some complex logic or conventions in
the provided information.

2 files changed, 23 insertions, 0 deletions

diff --git a/src/buildtool/build_engine/base_maps/rule_map.cpp b/src/buildtool/build_engine/base_maps/rule_map.cpp
index 93924941..ad242550 100644
--- a/src/buildtool/build_engine/base_maps/rule_map.cpp
+++ b/src/buildtool/build_engine/base_maps/rule_map.cpp
@@ -13,6 +13,7 @@ namespace BuildMaps::Base {
 namespace {
 
 auto const kRuleFields = std::unordered_set<std::string>{"anonymous",
+                                                         "artifacts_doc",
                                                          "config_doc",
                                                          "config_fields",
                                                          "config_transitions",
@@ -22,6 +23,8 @@ auto const kRuleFields = std::unordered_set<std::string>{"anonymous",
                                                          "field_doc",
                                                          "implicit",
                                                          "imports",
+                                                         "provides_doc",
+                                                         "runfiles_doc",
                                                          "string_fields",
                                                          "tainted",
                                                          "target_fields"};
diff --git a/src/buildtool/main/main.cpp b/src/buildtool/main/main.cpp
index 7c0d69c0..687cc888 100644
--- a/src/buildtool/main/main.cpp
+++ b/src/buildtool/main/main.cpp
@@ -1163,6 +1163,26 @@ auto DescribeTarget(std::string const& main_repo,
         std::cout << " Variables taken from the configuration\n";
         PrintFields(*config_vars, config_doc, " - ", "   | ");
     }
+    std::cout << " Result\n";
+    std::cout << " - Artifacts\n";
+    auto artifacts_doc = rdesc.find("artifacts_doc");
+    if (artifacts_doc != rdesc.end()) {
+        PrintDoc(*artifacts_doc, "   | ");
+    }
+    std::cout << " - Runfiles\n";
+    auto runfiles_doc = rdesc.find("runfiles_doc");
+    if (runfiles_doc != rdesc.end()) {
+        PrintDoc(*runfiles_doc, "   | ");
+    }
+    auto provides_doc = rdesc.find("provides_doc");
+    if (provides_doc != rdesc.end()) {
+        std::cout << " - Documented providers\n";
+        for (auto& el : provides_doc->items()) {
+            std::cout << "   - " << el.key() << "\n";
+            PrintDoc(el.value(), "     | ");
+        }
+    }
+
     std::cout << std::endl;
     return kExitSuccess;
 }