Document rule metdata.

README.md

@@ -47,7 +47,8 @@ They represent my personal interpretation and explanation of the standard.
 
 ## Work in progress
 
-I've just started writing these tutorials. I'll remove this notice when I think there's enough information to be useful.
+As you will see from the missing links in the table of contents, there's still much more I'd like to write about.
+Even so, I think there's enough useful information in these tutorials to be worth your while to read.
 
 ## <a id="contents"></a>Table of contents
 
@@ -62,7 +63,7 @@ I've just started writing these tutorials. I'll remove this notice when I think
   - [Logs and runs](docs/2-Basics.md#logs-runs)
   - [Property bags](docs/2-Basics.md#property-bags)
   - [Results](docs/2-Basics.md#results)
-    - [Messages](docs/2-Basics.md#messages)
+    - [Message](docs/2-Basics.md#message)
     - [Rule identifier](docs/2-Basics.md#rule-id)
     - [Level](docs/2-Basics.md#level)
     - [Locations](docs/2-Basics.md#locations)
@@ -71,7 +72,7 @@ I've just started writing these tutorials. I'll remove this notice when I think
   - [Artifacts](docs/2-Basics.md#artifacts)
     - [Defining artifacts](docs/2-Basics.md#defining-artifacts)
     - [Linking results to artifacts](docs/2-Basics.md#linking-artifacts)
-  - [Rule metadata (TODO)](docs/2-Basics.md#rule-metadata)
+  - [Rule metadata](docs/2-Basics.md#rule-metadata)
 - [Beyond the basics](docs/3-Beyond-basics.md)
   - [More about messages (TODO)](docs/3-Beyond-basics.md#more-about-messages)
   - [Invocations (TODO)](docs/3-Beyond-basics.md#invocations)

docs/1-Introduction.md

@@ -82,6 +82,8 @@ If we run ESLint with the SARIF formatter:
 
 ... we get:
 
+<a id="simple-example-file"></a>
+
 ```json
 {
   "version": "2.1.0",

docs/2-Basics.md

@@ -158,7 +158,7 @@ but some results might be purely informational.
     {
       "tool": {
         "driver": {
-          "name": "CodeScanner"
+          "name": "ESLint"
         }
       },
       "results": [
@@ -209,7 +209,7 @@ by opening the file specified by `physicalLocation.artifactLocation.uri` (`simpl
 The viewer will typically scroll the portion of the file specified by `physicalLocation.region` (line 1 in the example)
 into view, and highlight it.
 
-### <a id="messages"></a>Messages
+### <a id="message"></a>Message
 
 The only required property of a `result` object is the `message` property.
 
@@ -514,6 +514,29 @@ For each such property, the spec explains which array to look in.
 
 ## <a id="rule-metadata"></a>Rule metadata
 
+A SARIF log file can contain information about the analysis rules defined by the static analysis tool.
+The spec refers to this information as _rule metadata_.
+Rule metadata can include a complete description of the rule,
+its default severity level,
+one or more message strings (possibly including substitution sequences like `{0}`) to include in a result,
+and a URI where you can find more information about the rule.
+
+If rule metadata is present, then when a user selects a result in a SARIF file,
+a SARIF viewer can display the metadata for the rule that was violated.
+Here is a screen shot that shows the
+[Microsoft SARIF Viewer VSIX for Visual Studio](https://marketplace.visualstudio.com/items?itemName=WDGIS.MicrosoftSarifViewer)
+displaying the SARIF file shown in the [simple example](1-Introduction.md#simple-example-file) from the introduction.
+The user has selected the result in the Error List window at the bottom.
+On the right, the user has selected the Info tab in the SARIF Explorer,
+and viewer has displayed the help URI from the metadata for the `no-unused-vars` rule.
+
+![A SARIF viewer displays rule metadata for a result](../images/rule-metadata-for-a-result.png)
+
+Rule metadata is optional.
+An analysis tool can choose not to include it at all,
+to include metadata for only those rules that are relevant to the results,
+or to include metadata for all rules known to the tool.
+
 ## Notes
 
 <a id="note-1"></a>1. In future, SARIF might support other serializations of its underlying object model.