Fill in edge type descriptions (#1083)

Pull #1080 added in a description field for edge types, but put in a
placeholder message for each actual description. This pull adds in
descriptions for each edge type.

Test plan: `yarn test` passes, and additionally
`git grep 'TODO: Add a description for this edge type'` returns no hits.
Reviewed by @BrianLitwin and @wchargin.

src/analysis/types.js

@@ -80,23 +80,45 @@ export type EdgeType = {|
   // means. For example, for the GitHub REFERENCES edge type, the forwardName
   // is "references"
   +forwardName: string,
+
   // A brief descriptive name of what the "backward" direction of the edge
   // means. For example, for the GitHub REFERENCES edge type, the backwardName
   // is "referenced by"
   +backwardName: string,
+
   // The default weight for the forward direction of this edge.
   // We use `1` as a default value ("of normal importance").
   // The weights have linear importance, i.e. 2 is twice as important as 1.
   +defaultForwardWeight: number,
+
   // The default weight for the backward direction of this edge.
   // We use `1` as a default value ("of normal importance").
   // The weights have linear importance, i.e. 2 is twice as important as 1.
   +defaultBackwardWeight: number,
+
   // The address that will be used to test whether an edge is a member
   // of this EdgeType. A given edge `e` is a member of the type `t` if
   // `EdgeAddress.hasPrefix(e.address, t.prefix) == true`
   +prefix: EdgeAddressT,
+
   // The `description` property should be a human-readable string that makes
-  // it clear to a user what each EdgeType does
+  // it clear to a user what each EdgeType does.
+  //
+  // By convention, the first line of the description should be a sentence
+  // beginning with the word "Connects", which describes what kinds of nodes
+  // the edge connects and why. Optionally, you may provide examples and additional
+  // context after one blank link. Here is an example (for the "Merged As" edge).
+  //
+  // ```js
+  // const mergedAsDescription = dedent`\
+  //  Connects a GitHub pull request to the Git commit it merged.
+  //
+  //  A pull request can have either one or zero Merged As edges, depending on
+  //  whether or not it was ever merged.
+  //  `
+  // ```
+  //
+  // (Note the use of the `util/dedent.js` makes it easier to write multi-lined
+  // strings with clean formatting.)
   +description: string,
 |};

src/explorer/pagerankTable/Aggregation.test.js

@@ -157,7 +157,7 @@ describe("explorer/pagerankTable/Aggregation", () => {
       defaultForwardWeight: 1,
       defaultBackwardWeight: 1,
       prefix: EdgeAddress.fromParts(["look", "like"]),
-      description: "TODO: Add a description for this EdgeType",
+      description: "Connects example nodes for testing purposes.",
     };
     function aggView(aggregation: FlatAggregation) {
       const el = shallow(<AggregationView aggregation={aggregation} />);

src/explorer/pagerankTable/aggregate.test.js

@@ -66,7 +66,7 @@ describe("explorer/pagerankTable/aggregate", () => {
         defaultForwardWeight: 1,
         defaultBackwardWeight: 1,
         prefix: EdgeAddress.fromParts(["foo"]),
-        description: "TODO: Add a description for this EdgeType",
+        description: "Connects example foo edges.",
       },
       bar: {
         forwardName: "bars",
@@ -74,7 +74,7 @@ describe("explorer/pagerankTable/aggregate", () => {
         defaultForwardWeight: 1,
         defaultBackwardWeight: 1,
         prefix: EdgeAddress.fromParts(["bar"]),
-        description: "TODO: Add a description for this EdgeType",
+        description: "Connects example bar edges.",
       },
       empty: {
         forwardName: "empty",
@@ -82,7 +82,7 @@ describe("explorer/pagerankTable/aggregate", () => {
         defaultForwardWeight: 1,
         defaultBackwardWeight: 1,
         prefix: EdgeAddress.empty,
-        description: "TODO: Add a description for this EdgeType",
+        description: "Connects arbitrary edges.",
       },
     };
     const edgeTypesArray = [edgeTypes.foo, edgeTypes.bar];

src/plugins/demo/declaration.js

@@ -28,7 +28,7 @@ export const assemblesEdgeType: EdgeType = Object.freeze({
   backwardName: "is assembled by",
   defaultBackwardWeight: 2 ** -2,
   prefix: EdgeAddress.fromParts(["factorio", "assembles"]),
-  description: "TODO: Add a description for this EdgeType",
+  description: "Connects assembly machines to products they assemble.",
 });
 
 export const transportsEdgeType: EdgeType = Object.freeze({
@@ -37,7 +37,7 @@ export const transportsEdgeType: EdgeType = Object.freeze({
   backwardName: "is transported by",
   defaultBackwardWeight: 2 ** -1,
   prefix: EdgeAddress.fromParts(["factorio", "transports"]),
-  description: "TODO: Add a description for this EdgeType",
+  description: "Connects transporter belts to objects they transport.",
 });
 
 export const declaration: PluginDeclaration = Object.freeze({

src/plugins/git/declaration.js

@@ -19,7 +19,7 @@ const hasParentEdgeType = Object.freeze({
   prefix: E.Prefix.hasParent,
   defaultForwardWeight: 1,
   defaultBackwardWeight: 1,
-  description: "TODO: Add a description for this EdgeType",
+  description: "Connects a Git commit to its parent commit(s).",
 });
 
 const nodeTypes = Object.freeze([commitNodeType]);

src/plugins/github/declaration.js

@@ -3,6 +3,7 @@
 import type {PluginDeclaration} from "../../analysis/pluginDeclaration";
 import * as N from "./nodes";
 import * as E from "./edges";
+import dedent from "../../util/dedent";
 
 const repoNodeType = Object.freeze({
   name: "Repository",
@@ -76,7 +77,11 @@ const authorsEdgeType = Object.freeze({
   defaultForwardWeight: 1 / 2,
   defaultBackwardWeight: 1,
   prefix: E.Prefix.authors,
-  description: "TODO: Add a description for this EdgeType",
+  description: dedent`\
+    Connects a GitHub account to a post that they authored.
+
+    Examples of posts include issues, pull requests, and comments.
+  `,
 });
 
 const hasParentEdgeType = Object.freeze({
@@ -85,7 +90,12 @@ const hasParentEdgeType = Object.freeze({
   defaultForwardWeight: 1,
   defaultBackwardWeight: 1 / 4,
   prefix: E.Prefix.hasParent,
-  description: "TODO: Add a description for this EdgeType",
+  description: dedent`\
+    Connects a GitHub entity to its child entities.
+
+    For example, a Repository has Issues and Pull Requests as children, and a
+    Pull Request has comments and reviews as children.
+  `,
 });
 
 const mergedAsEdgeType = Object.freeze({
@@ -94,7 +104,9 @@ const mergedAsEdgeType = Object.freeze({
   defaultForwardWeight: 1 / 2,
   defaultBackwardWeight: 1,
   prefix: E.Prefix.mergedAs,
-  description: "TODO: Add a description for this EdgeType",
+  description: dedent`\
+    Connects a GitHub pull request to the Git commit that it merges.
+  `,
 });
 
 const referencesEdgeType = Object.freeze({
@@ -103,7 +115,13 @@ const referencesEdgeType = Object.freeze({
   defaultForwardWeight: 1,
   defaultBackwardWeight: 0,
   prefix: E.Prefix.references,
-  description: "TODO: Add a description for this EdgeType",
+  description: dedent`\
+    Connects a GitHub post to an entity that it references.
+
+    For example, if you write a GitHub issue comment that says "thanks
+    @username for pull #1337", it will create references edges to both the user
+    @username, and to pull #1337 in the same repository.
+  `,
 });
 
 const mentionsAuthorEdgeType = Object.freeze({
@@ -112,7 +130,15 @@ const mentionsAuthorEdgeType = Object.freeze({
   defaultForwardWeight: 1,
   defaultBackwardWeight: 0,
   prefix: E.Prefix.mentionsAuthor,
-  description: "TODO: Add a description for this EdgeType",
+  description: dedent`\
+    Connects a post that mentions a user to posts in the same thread that
+    were authored by the mentioned user.
+
+    The intuition is that if a post is mentioning an author by name,
+    their contributions in that thread are probably particularly valuable.
+
+    This is an experimental feature and may be removed in a future version of SourceCred.
+  `,
 });
 
 const reactsHeartEdgeType = Object.freeze({
@@ -121,7 +147,9 @@ const reactsHeartEdgeType = Object.freeze({
   defaultForwardWeight: 2,
   defaultBackwardWeight: 0,
   prefix: E.Prefix.reactsHeart,
-  description: "TODO: Add a description for this EdgeType",
+  description: dedent`\
+    Connects users to posts to which they gave a ❤️ reaction.
+  `,
 });
 
 const reactsThumbsUpEdgeType = Object.freeze({
@@ -130,7 +158,9 @@ const reactsThumbsUpEdgeType = Object.freeze({
   defaultForwardWeight: 1,
   defaultBackwardWeight: 0,
   prefix: E.Prefix.reactsThumbsUp,
-  description: "TODO: Add a description for this EdgeType",
+  description: dedent`\
+    Connects users to posts to which they gave a 👍 reaction.
+  `,
 });
 
 const reactsHoorayEdgeType = Object.freeze({
@@ -139,7 +169,9 @@ const reactsHoorayEdgeType = Object.freeze({
   defaultForwardWeight: 4,
   defaultBackwardWeight: 0,
   prefix: E.Prefix.reactsHooray,
-  description: "TODO: Add a description for this EdgeType",
+  description: dedent`\
+    Connects users to posts to which they gave a 🎉 reaction.
+  `,
 });
 
 const reactsRocketEdgeType = Object.freeze({
@@ -148,7 +180,9 @@ const reactsRocketEdgeType = Object.freeze({
   defaultForwardWeight: 1,
   defaultBackwardWeight: 0,
   prefix: E.Prefix.reactsRocket,
-  description: "TODO: Add a description for this EdgeType",
+  description: dedent`\
+    Connects users to posts to which they gave a 🚀 reaction.
+  `,
 });
 
 const edgeTypes = Object.freeze([