Improve documenatation of our internal rules

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

6 files changed, 85 insertions, 1 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"]
diff --git a/data/RULES b/data/RULES
index 17ac2d9..172fc2f 100644
--- a/data/RULES
+++ b/data/RULES
@@ -9,6 +9,11 @@
       , "Individual directory components are joined with \"/\"."
       ]
     }
+  , "artifacts_doc":
+    [ "The runfiles of the \"srcs\" targets staged to the directory"
+    , "specified in \"stage\"."
+    ]
+  , "runfiles_doc": ["Same as artifacts"]
   , "expression":
     { "type": "let*"
     , "bindings":
diff --git a/patch/RULES b/patch/RULES
index 87bf575..15bc818 100644
--- a/patch/RULES
+++ b/patch/RULES
@@ -7,6 +7,9 @@
       ["The single source file to patch, typically an explict file reference."]
     , "patch": ["The patch to apply."]
     }
+  , "artifacts_doc":
+    ["The patched file, staged to the position the of the original file"]
+  , "runfiles_doc": ["Same as artifacts"]
   , "imports":
     { "stage_field": ["./", "..", "stage_singleton_field"]
     , "stage_artifact": ["./", "..", "stage_artifact_to_singleton_field"]
diff --git a/proto/RULES b/proto/RULES
index b6ce000..74182a9 100644
--- a/proto/RULES
+++ b/proto/RULES
@@ -1,6 +1,34 @@
 { "library":
-  { "target_fields": ["srcs", "deps"]
+  { "doc":
+    [ "A proto library as abtract data structure."
+    , ""
+    , "Such a libray does not produce any artifacts itself, but it can be"
+    , "used as a dependency for various language-specific rules."
+    ]
+  , "target_fields": ["srcs", "deps"]
   , "string_fields": ["stage", "name", "service"]
+  , "field_doc":
+    { "srcs": ["The proto files for this library"]
+    , "deps": ["Any other proto library this library depends on"]
+    , "stage":
+      [ "The directory to stage the source files to."
+      , "Directory components are joined by \"/\"."
+      ]
+    , "name": ["The name of the (abstract) library."]
+    , "service":
+      [ "If non empty, generate a service library (with acces sto \"rpc\""
+      , "definitions) instead of a regular one."
+      ]
+    }
+  , "artifacts_doc": ["None"]
+  , "runfiles_doc": ["None"]
+  , "provides_doc":
+    { "proto":
+      [ "A list containing a single target-graph node with the defintion of"
+      , "this proto library. The node types generated are \"library\" and"
+      , "\"service library\"."
+      ]
+    }
   , "expression":
     { "type": "let*"
     , "bindings":
diff --git a/shell/test/RULES b/shell/test/RULES
index d61f21f..74a0b78 100644
--- a/shell/test/RULES
+++ b/shell/test/RULES
@@ -26,6 +26,20 @@
       ]
     }
   , "tainted": ["test"]
+  , "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"
+    , "work:   In this directory, all the files specified to \"keep\" are staged"
+    , "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."
+    ]
   , "implicit":
     {"runner": ["test_runner.sh"], "summarizer": ["test_summary.py"]}
   , "imports":