Improve documenatation of our internal rules

In particular, document the result for the most important
rules.

2 files changed, 34 insertions, 0 deletions

diff --git a/CC/RULES b/CC/RULES
index 01aa634..cfe1ae3 100644
--- a/CC/RULES
+++ b/CC/RULES
@@ -115,6 +115,8 @@
       , "Path segments are joined with \"/\"."
       ]
     }
+  , "artifacts_doc": ["The single tree artifact staged to the given location"]
+  , "runfiles_doc": ["Same as artifacts"]
   , "expression":
     { "type": "let*"
     , "bindings":
@@ -227,6 +229,23 @@
       , "choice"
       ]
     }
+  , "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"
+      ]
+    }
   , "anonymous":
     { "proto-deps":
       { "target": "proto"
@@ -372,6 +391,8 @@
       , "taken from the [\"CC\", \"defaults\"] target"
       ]
     }
+  , "artifacts_doc": ["The final binary, staged to the given directory"]
+  , "runfiles_doc": ["None"]
   , "anonymous":
     { "proto-deps":
       { "target": "proto"
diff --git a/CC/test/RULES b/CC/test/RULES
index fc3ab97..50d0dce 100644
--- a/CC/test/RULES
+++ b/CC/test/RULES
@@ -43,6 +43,19 @@
       , "command line for running the test binary."
       ]
     }
+  , "artifacts_doc":
+    [ "result: the result of this test (\"PASS\" or \"FAIL\"); useful for"
+    , "        generating test reports."
+    , "stdout/stderr: Any output the invocation of the test binary produced on"
+    , "        the respective file descriptor"
+    , "time-start/time-stop: The time (decimally coded) in seconds since the"
+    , "        epoch when the test invocation started and ended."
+    ]
+  , "runfiles_doc":
+    [ "A tree consisting of the artifacts staged at the name of the test."
+    , "As the built-in \"install\" rule only takes the runfiles of its \"deps\""
+    , "argument, this gives an easy way of defining test suites."
+    ]
   , "imports":
     { "artifacts": ["./", "../..", "field_artifacts"]
     , "compile-deps": ["./", "..", "compile-deps"]