From e0762303d466c6a8f86324eb84e3120c29beddb0 Mon Sep 17 00:00:00 2001 From: Ana Noemi <480753+anthrocypher@users.noreply.github.com> Date: Mon, 21 Jan 2019 19:16:56 -0500 Subject: [PATCH] Add descriptions for NodeTypes (#1044) * Add descriptions for NodeTypes As highlighted by @decentralion in issue #807, we need descriptions for Node and Edge types in the UI to explain to users what each Node and Edge type does. This PR modifies the type definition for `NodeType` and adds a `+description: string` field, then updates all NodeTypes throughout the codebase with descriptions. Test plan: Verify that all tests pass and the descriptions makes sense. --- src/analysis/fallbackDeclaration.js | 2 ++ src/analysis/types.js | 3 +++ src/explorer/pagerankTable/Aggregation.test.js | 1 + src/explorer/pagerankTable/aggregate.test.js | 15 ++++++++++++--- src/plugins/demo/declaration.js | 2 ++ src/plugins/git/declaration.js | 4 +++- src/plugins/github/declaration.js | 7 +++++++ 7 files changed, 30 insertions(+), 4 deletions(-) diff --git a/src/analysis/fallbackDeclaration.js b/src/analysis/fallbackDeclaration.js index 65281e5..bea55ac 100644 --- a/src/analysis/fallbackDeclaration.js +++ b/src/analysis/fallbackDeclaration.js @@ -13,6 +13,8 @@ export const fallbackNodeType: NodeType = Object.freeze({ pluralName: "nodes", prefix: NodeAddress.empty, defaultWeight: 1, + description: + "The fallback NodeType for nodes which don't have any other type", }); export const fallbackEdgeType: EdgeType = Object.freeze({ diff --git a/src/analysis/types.js b/src/analysis/types.js index d026bdb..82ed4bd 100644 --- a/src/analysis/types.js +++ b/src/analysis/types.js @@ -66,6 +66,9 @@ export type NodeType = {| // normal importance", and the weights scale linearly from there (i.e. 2 // means twice as important). +defaultWeight: number, + // The `description` property should be a human-readable string that makes + // it clear to a user what each NodeType does + +description: string, |}; /** diff --git a/src/explorer/pagerankTable/Aggregation.test.js b/src/explorer/pagerankTable/Aggregation.test.js index c575804..7aa97ef 100644 --- a/src/explorer/pagerankTable/Aggregation.test.js +++ b/src/explorer/pagerankTable/Aggregation.test.js @@ -149,6 +149,7 @@ describe("explorer/pagerankTable/Aggregation", () => { pluralName: "whatDoth", defaultWeight: 1, prefix: NodeAddress.empty, + description: "An example NodeType for testing purposes", }; const edgeType: EdgeType = { forwardName: "marsellus", diff --git a/src/explorer/pagerankTable/aggregate.test.js b/src/explorer/pagerankTable/aggregate.test.js index be9098b..f15f198 100644 --- a/src/explorer/pagerankTable/aggregate.test.js +++ b/src/explorer/pagerankTable/aggregate.test.js @@ -1,6 +1,6 @@ // @flow -import {EdgeAddress, NodeAddress} from "../../core/graph"; +import {EdgeAddress, NodeAddress, type NodeAddressT} from "../../core/graph"; import * as NullUtil from "../../util/null"; import { aggregateByNodeType, @@ -9,42 +9,51 @@ import { aggregateFlat, aggregationKey, } from "./aggregate"; +import type {NodeType} from "../../analysis/types"; describe("explorer/pagerankTable/aggregate", () => { // TODO: If making major modifications to these tests, consider switching // from the hand-maintained connections and types, and instead use the demo // adadpters from app/adapters/demoAdapters function example() { - const nodes = { + const nodes: {+[string]: NodeAddressT} = { root: NodeAddress.fromParts(["root"]), zap: NodeAddress.fromParts(["zap"]), kif: NodeAddress.fromParts(["kif"]), }; - const nodeTypes = { + const nodeTypes: {+[string]: NodeType} = { root: { name: "root", pluralName: "roots", prefix: nodes.root, defaultWeight: 0, + description: + "This NodeType corresponds to the node with the address named `root`", }, zap: { name: "zap", pluralName: "zaps", prefix: nodes.zap, defaultWeight: 0, + description: + "This NodeType corresponds to the node with the address named `zap`", }, kif: { name: "kif", pluralName: "kifs", prefix: nodes.kif, defaultWeight: 0, + description: + "This NodeType corresponds to the node with the address named `kif`", }, empty: { name: "empty", pluralName: "empties", prefix: NodeAddress.empty, defaultWeight: 0, + description: + "This NodeType is for an empty address, which matches every node", }, }; diff --git a/src/plugins/demo/declaration.js b/src/plugins/demo/declaration.js index c5e837f..6b9bbac 100644 --- a/src/plugins/demo/declaration.js +++ b/src/plugins/demo/declaration.js @@ -11,6 +11,7 @@ export const inserterNodeType: NodeType = Object.freeze({ pluralName: "inserters", prefix: NodeAddress.fromParts(["factorio", "inserter"]), defaultWeight: 1, + description: "Nodes for Factorio inserter objects in demo plugin", }); export const machineNodeType: NodeType = Object.freeze({ @@ -18,6 +19,7 @@ export const machineNodeType: NodeType = Object.freeze({ pluralName: "machines", prefix: NodeAddress.fromParts(["factorio", "machine"]), defaultWeight: 2, + description: "Nodes for Factorio machine objects in demo plugin", }); export const assemblesEdgeType: EdgeType = Object.freeze({ diff --git a/src/plugins/git/declaration.js b/src/plugins/git/declaration.js index f9be376..66c588a 100644 --- a/src/plugins/git/declaration.js +++ b/src/plugins/git/declaration.js @@ -1,14 +1,16 @@ // @flow import type {PluginDeclaration} from "../../analysis/pluginDeclaration"; +import type {NodeType} from "../../analysis/types"; import * as N from "./nodes"; import * as E from "./edges"; -const commitNodeType = Object.freeze({ +const commitNodeType: NodeType = Object.freeze({ name: "Commit", pluralName: "Commits", prefix: N.Prefix.commit, defaultWeight: 2, + description: "NodeType representing a git commit", }); const hasParentEdgeType = Object.freeze({ diff --git a/src/plugins/github/declaration.js b/src/plugins/github/declaration.js index 6207a5c..0684f26 100644 --- a/src/plugins/github/declaration.js +++ b/src/plugins/github/declaration.js @@ -9,6 +9,7 @@ const repoNodeType = Object.freeze({ pluralName: "Repositories", prefix: N.Prefix.repo, defaultWeight: 4, + description: "NodeType for a GitHub repository", }); const issueNodeType = Object.freeze({ @@ -16,6 +17,7 @@ const issueNodeType = Object.freeze({ pluralName: "Issues", prefix: N.Prefix.issue, defaultWeight: 2, + description: "NodeType for a GitHub issue", }); const pullNodeType = Object.freeze({ @@ -23,6 +25,7 @@ const pullNodeType = Object.freeze({ pluralName: "Pull requests", prefix: N.Prefix.pull, defaultWeight: 4, + description: "NodeType for a GitHub pull request", }); const reviewNodeType = Object.freeze({ @@ -30,6 +33,7 @@ const reviewNodeType = Object.freeze({ pluralName: "Pull request reviews", prefix: N.Prefix.review, defaultWeight: 1, + description: "NodeType for a GitHub code review", }); const commentNodeType = Object.freeze({ @@ -37,6 +41,7 @@ const commentNodeType = Object.freeze({ pluralName: "Comments", prefix: N.Prefix.comment, defaultWeight: 1, + description: "NodeType for a GitHub comment", }); const userNodeType = Object.freeze({ @@ -44,6 +49,7 @@ const userNodeType = Object.freeze({ pluralName: "Users", prefix: N.Prefix.user, defaultWeight: 1, + description: "NodeType for a GitHub user", }); const botNodeType = Object.freeze({ @@ -51,6 +57,7 @@ const botNodeType = Object.freeze({ pluralName: "Bots", prefix: N.Prefix.bot, defaultWeight: 0.25, + description: "NodeType for a GitHub bot account", }); const nodeTypes = Object.freeze([