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.