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.

1 files changed, 31 insertions, 3 deletions

diff --git a/doc/concepts/doc-strings.org b/doc/concepts/doc-strings.org
index 387749df..00ecea27 100644
--- a/doc/concepts/doc-strings.org
+++ b/doc/concepts/doc-strings.org
@@ -30,13 +30,21 @@ the empy array or the empty map is taken as default, respectively.
 
 Each rule is described as a JSON object with a fixed set of keys.
 So having fixed keys for documentation does not cause conflicts.
-More precisely, the keys ~doc~, ~field doc~, and ~config_doc~
+More precisely, the keys ~doc~, ~field doc~, ~config_doc~,
+~artifacts_doc~, ~runfiles_doc~, and ~provides_doc~
 are reserved for documentation. Here, ~doc~ has to be a list of
 strings describing the rule in general. ~field doc~ has to be a map
 from (some of) the field names to an array of strings, containing
 additional information on that particular field. ~config_doc~ has
 to be a map from (some of) the config variables to an array of
-strings describing the respective variable.
+strings describing the respective variable. ~artifacts_doc~ is
+an array of strings describing the artifacts produced by the rule.
+~runfiles_doc~ is an array of strings describing the runfiles produced
+by this rule. Finally, ~provides_doc~ is a map describing (some
+of) the providers by that rule; as opposed to fields or config
+variables there is no authoritative list of providers given elsewhere
+in the rule, so it is up to the rule author to give an accurate
+documentation on the provided data.
 
 *** Example
 
@@ -78,6 +86,23 @@ strings describing the respective variable.
       , "to be used. The compiler is also used to launch the preprocessor."
       ]
     }
+  , "artifacts_doc":
+    ["The actual library (libname.a) staged in the specified directory"]
+  , "runfiles_doc": ["The public headers of this library"]
+  , "provides_doc":
+    { "compile-deps":
+      [ "Map of artifacts specifying any additional files that, besides the runfiles,"
+      , "have to be present in compile actions of targets depending on this library"
+      ]
+    , "link-deps":
+      [ "Map of artifacts specifying any additional files that, besides the artifacts,"
+      , "have to be present in a link actions of targets depending on this library"
+      ]
+    , "link-args":
+      [ "List of strings that have to be added to the command line for linking actions"
+      , "in targets depending on on this library"
+      ]
+    }
   , "expression": { ... }
   }
 }
@@ -114,4 +139,7 @@ it fully, i.e., prints in human-readable form
 - the documentation for the rule
 - all the fields available for that rule together with
   - their type (~string_field~, ~target_field~, etc), and
-  - their documentation.
+  - their documentation,
+- all the configuration variables of the rule with their
+  documentation (if given), and
+- the documented providers.