@eagleoutice/flowr 2.1.7 → 2.1.9

package/dataflow/environments/environment.d.ts

@@ -7,19 +7,22 @@
 import type { Identifier, IdentifierDefinition, IdentifierReference } from './identifier';
 import type { DataflowGraph } from '../graph/graph';
 import type { ControlDependency } from '../info';
+/**
+ * Marks the reference as maybe (i.e., as controlled by a set of {@link IdentifierReference#controlDependencies|control dependencies}).
+ */
 export declare function makeReferenceMaybe(ref: IdentifierReference, graph: DataflowGraph, environments: REnvironmentInformation, includeDefs: boolean, defaultCd?: ControlDependency | undefined): IdentifierReference;
 export declare function makeAllMaybe(references: readonly IdentifierReference[] | undefined, graph: DataflowGraph, environments: REnvironmentInformation, includeDefs: boolean, defaultCd?: ControlDependency | undefined): IdentifierReference[];
 export type EnvironmentMemory = Map<Identifier, IdentifierDefinition[]>;
+/** A single entry/scope within an {@link REnvironmentInformation} */
 export interface IEnvironment {
-    /** unique and internally generated identifier -- will not be used for comparison but assists debugging for tracking identities */
+    /** Unique and internally generated identifier -- will not be used for comparison but helps with debugging for tracking identities */
     readonly id: number;
     /** Lexical parent of the environment, if any (can be manipulated by R code) */
     parent: IEnvironment;
-    /**
-   * Maps to exactly one definition of an identifier if the source is known, otherwise to a list of all possible definitions
-   */
+    /** Maps to exactly one definition of an identifier if the source is known, otherwise to a list of all possible definitions */
     memory: EnvironmentMemory;
 }
+/** @see REnvironmentInformation */
 export declare class Environment implements IEnvironment {
     readonly id: number;
     parent: IEnvironment;
@@ -27,11 +30,26 @@ export declare class Environment implements IEnvironment {
     constructor(parent: IEnvironment);
 }
 /**
- * First of all, yes, R stores its environments differently, potentially even with a different differentiation between
- * the `baseenv`, the `emptyenv`and other default environments. Yet, during dataflow we want sometimes to know more (static
- * reference information) and sometimes know less (to be honest we do not want that,
+ * An environment describes a ({@link IEnvironment#parent|scoped}) mapping of names to their definitions ({@link EnvironmentMemory}).
+ *
+ * First, yes, R stores its environments differently, potentially even with another differentiation between
+ * the `baseenv`, the `emptyenv`, and other default environments (see https://adv-r.hadley.nz/environments.html).
+ * Yet, during the dataflow analysis, we want sometimes to know more (static {@link IdentifierDefinition|reference information})
+ * and sometimes know less (to be honest, we do not want that,
  * but statically determining all attached environments is theoretically impossible --- consider attachments by user input).
- * One example would be maps holding a potential list of all definitions of a variable, if we do not know the execution path (like with `if(x) A else B`).
+ *
+ * One important environment is the {@link BuiltInEnvironment} which contains the default definitions for R's built-in functions and constants.
+ * Please use {@link initializeCleanEnvironments} to initialize the environments (which includes the built-ins).
+ * During serialization, you may want to rely on the {@link builtInEnvJsonReplacer} to avoid the huge built-in environment.
+ *
+ *
+ * @see {@link define} - to define a new {@link IdentifierDefinition|identifier definition} within an environment
+ * @see {@link resolveByName} - to resolve an {@link Identifier|identifier/name} to its {@link IdentifierDefinition|definitions} within an environment
+ * @see {@link makeReferenceMaybe} - to attach control dependencies to a reference
+ * @see {@link pushLocalEnvironment} - to create a new local scope
+ * @see {@link popLocalEnvironment} - to remove the current local scope
+ * @see {@link appendEnvironment} - to append an environment to the current one
+ * @see {@link overwriteEnvironment} - to overwrite the definitions in the current environment with those of another one
  */
 export interface REnvironmentInformation {
     /**  The currently active environment (the stack is represented by the currently active {@link IEnvironment#parent}). Environments are maintained within the dataflow graph. */
@@ -39,7 +57,27 @@ export interface REnvironmentInformation {
     /** nesting level of the environment, will be `0` for the global/root environment */
     readonly level: number;
 }
+/**
+ * The built-in {@link REnvironmentInformation|environment} is the root of all environments.
+ *
+ * For its default content (when not overwritten by a flowR config),
+ * see the {@link DefaultBuiltinConfig}.
+ */
 export declare const BuiltInEnvironment: Environment;
+/**
+ * The twin of the {@link BuiltInEnvironment} but with less built ins defined for
+ * cases in which we want some commonly overwritten variables to remain open.
+ * If you do not know if you need the empty environment, you do not need the empty environment (right now).
+ *
+ * @see {@link BuiltInEnvironment}
+ */
 export declare const EmptyBuiltInEnvironment: IEnvironment;
+/**
+ * Initialize a new {@link REnvironmentInformation|environment} with the built-ins.
+ * See {@link EmptyBuiltInEnvironment} for the case `fullBuiltIns = false`.
+ */
 export declare function initializeCleanEnvironments(fullBuiltIns?: boolean): REnvironmentInformation;
+/**
+ * Helps to serialize an environment, but replaces the built-in environment with a placeholder.
+ */
 export declare function builtInEnvJsonReplacer(k: unknown, v: unknown): unknown;

package/dataflow/environments/environment.js

@@ -9,6 +9,9 @@ const identifier_1 = require("./identifier");
 const built_in_1 = require("./built-in");
 const resolve_by_name_1 = require("./resolve-by-name");
 const json_1 = require("../../util/json");
+/**
+ * Marks the reference as maybe (i.e., as controlled by a set of {@link IdentifierReference#controlDependencies|control dependencies}).
+ */
 function makeReferenceMaybe(ref, graph, environments, includeDefs, defaultCd = undefined) {
     const node = graph.get(ref.nodeId, true);
     if (includeDefs) {
@@ -42,6 +45,7 @@ function makeAllMaybe(references, graph, environments, includeDefs, defaultCd =
     return references.map(ref => makeReferenceMaybe(ref, graph, environments, includeDefs, defaultCd));
 }
 let environmentIdCounter = 0;
+/** @see REnvironmentInformation */
 class Environment {
     id = environmentIdCounter++;
     parent;
@@ -52,14 +56,30 @@ class Environment {
     }
 }
 exports.Environment = Environment;
-/* the built-in environment is the root of all environments */
+/**
+ * The built-in {@link REnvironmentInformation|environment} is the root of all environments.
+ *
+ * For its default content (when not overwritten by a flowR config),
+ * see the {@link DefaultBuiltinConfig}.
+ */
 exports.BuiltInEnvironment = new Environment(undefined);
 exports.BuiltInEnvironment.memory = undefined;
+/**
+ * The twin of the {@link BuiltInEnvironment} but with less built ins defined for
+ * cases in which we want some commonly overwritten variables to remain open.
+ * If you do not know if you need the empty environment, you do not need the empty environment (right now).
+ *
+ * @see {@link BuiltInEnvironment}
+ */
 exports.EmptyBuiltInEnvironment = {
     id: exports.BuiltInEnvironment.id,
     memory: undefined,
     parent: undefined
 };
+/**
+ * Initialize a new {@link REnvironmentInformation|environment} with the built-ins.
+ * See {@link EmptyBuiltInEnvironment} for the case `fullBuiltIns = false`.
+ */
 function initializeCleanEnvironments(fullBuiltIns = true) {
     exports.BuiltInEnvironment.memory ??= built_in_1.BuiltInMemory;
     exports.EmptyBuiltInEnvironment.memory ??= built_in_1.EmptyBuiltInMemory;
@@ -68,6 +88,9 @@ function initializeCleanEnvironments(fullBuiltIns = true) {
         level: 0
     };
 }
+/**
+ * Helps to serialize an environment, but replaces the built-in environment with a placeholder.
+ */
 function builtInEnvJsonReplacer(k, v) {
     if (v === exports.BuiltInEnvironment) {
         return '<BuiltInEnvironment>';

package/dataflow/environments/identifier.d.ts

@@ -5,9 +5,17 @@ export type Identifier = string & {
     __brand?: 'identifier';
 };
 /**
- * Each reference only has exactly one reference type, stored as the respective number.
- * However, when checking we may want to allow for one of several types,
+ * Each reference has exactly one reference type, stored as the respective number.
+ * However, when checking, we may want to allow for one of several types,
  * allowing the combination of the respective bitmasks.
+ *
+ * Having reference types is important as R separates a variable definition from
+ * a function when resolving an {@link Identifier|identifier}.
+ * In `c <- 3; print(c(1, 2))` the call to `c` works normally (as the vector constructor),
+ * while writing `c <- function(...) ..1` overshadows the built-in and causes `print` to only output the first element.
+ *
+ * @see {@link isReferenceType} - for checking if a (potentially joint) reference type contains a certain type
+ * @see {@link ReferenceTypeReverseMapping} - for debugging
  */
 export declare enum ReferenceType {
     /** The identifier type is unknown */
@@ -27,19 +35,38 @@ export declare enum ReferenceType {
     /** The identifier is defined by a built-in function */
     BuiltInFunction = 128
 }
+/** Reverse mapping of the reference types so you can get the name from the bitmask (useful for debugging) */
 export declare const ReferenceTypeReverseMapping: Map<ReferenceType, string>;
 /**
  * Check if the reference types have an overlapping type!
  */
 export declare function isReferenceType(t: ReferenceType, target: ReferenceType): boolean;
+/**
+ * Describes all types of reference (definitions) that can appear within a graph (i.e., that are not built-in like the
+ * default definition for the assignment operator `<-`).
+ *
+ * @see {@link InGraphIdentifierDefinition} - for the definition of an identifier within the graph
+ */
 export type InGraphReferenceType = Exclude<ReferenceType, ReferenceType.BuiltInConstant | ReferenceType.BuiltInFunction>;
 /**
- * Something like `a` in `b <- a`.
- * Without any surrounding information, `a` will produce the identifier reference `a`.
- * Similarly, `b` will create a reference.
+ * An identifier reference points to a variable like `a` in `b <- a`.
+ * Without any surrounding code, `a` will produce the identifier reference `a`.
+ * Similarly, `b` will create a reference (although it will be an {@link IdentifierDefinition|identifier definition}
+ * which adds even more information).
+ *
+ * In general,
+ * references are merely pointers (with meta-information) to a vertex in the {@link DataflowGraph|dataflow graph}.
+ * In the context of the extractor, for example,
+ * they indicate the references that are currently (during the analysis at this given node)
+ * {@link DataflowInformation#in|read (`in`)}, {@link DataflowInformation#out|written (`out`)},
+ * or {@link DataflowInformation#unknownReferences|unknown (`unknownReferences`)}.
+ *
+ * @see {@link InGraphIdentifierDefinition}
  */
 export interface IdentifierReference {
-    /** Node which represents the reference in the AST */
+    /**
+     * The id of the node which represents the reference in the {@link NormalizedAst|normalized AST} and the {@link DataflowGraph|dataflow graph}.
+     */
     readonly nodeId: NodeId;
     /** Name the reference is identified by (e.g., the name of the variable), undefined if the reference is "artificial" (e.g., anonymous) */
     readonly name: Identifier | undefined;
@@ -51,13 +78,28 @@ export interface IdentifierReference {
      */
     controlDependencies: ControlDependency[] | undefined;
 }
+/**
+ * The definition of an {@link Identifier|identifier} within the {@link DataflowGraph|graph}.
+ * This extends on the {@link IdentifierReference}
+ * by adding the {@link NodeId} of the definition
+ * (and using `type` to mark the object type).
+ *
+ * Within a code snippet like `a <- 3`, the symbol processor will first create an
+ * {@link IdentifierReference|identifier reference} for `a` to reference the use
+ * and then promote it to an {@link InGraphIdentifierDefinition|identifier definition}.
+ *
+ * @see {@link IdentifierReference}
+ */
 interface InGraphIdentifierDefinition extends IdentifierReference {
     readonly type: InGraphReferenceType;
     /** The assignment (or whatever, like `assign` function call) node which ultimately defined this identifier */
     readonly definedAt: NodeId;
 }
 /**
- * Stores the definition of an identifier within an {@link IEnvironment}
+ * Stores the definition of an identifier within an {@link IEnvironment}.
+ *
+ * {@link BuiltInIdentifierDefinition} and {@link BuiltInIdentifierConstant} are used for built-in functions and constants only,
+ * so the most important one for your day-to-day R script is the {@link InGraphIdentifierDefinition}.
  */
 export type IdentifierDefinition = InGraphIdentifierDefinition | BuiltInIdentifierDefinition | BuiltInIdentifierConstant;
 export {};

package/dataflow/environments/identifier.js

@@ -3,9 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReferenceTypeReverseMapping = exports.ReferenceType = void 0;
 exports.isReferenceType = isReferenceType;
 /**
- * Each reference only has exactly one reference type, stored as the respective number.
- * However, when checking we may want to allow for one of several types,
+ * Each reference has exactly one reference type, stored as the respective number.
+ * However, when checking, we may want to allow for one of several types,
  * allowing the combination of the respective bitmasks.
+ *
+ * Having reference types is important as R separates a variable definition from
+ * a function when resolving an {@link Identifier|identifier}.
+ * In `c <- 3; print(c(1, 2))` the call to `c` works normally (as the vector constructor),
+ * while writing `c <- function(...) ..1` overshadows the built-in and causes `print` to only output the first element.
+ *
+ * @see {@link isReferenceType} - for checking if a (potentially joint) reference type contains a certain type
+ * @see {@link ReferenceTypeReverseMapping} - for debugging
  */
 var ReferenceType;
 (function (ReferenceType) {
@@ -26,6 +34,7 @@ var ReferenceType;
     /** The identifier is defined by a built-in function */
     ReferenceType[ReferenceType["BuiltInFunction"] = 128] = "BuiltInFunction";
 })(ReferenceType || (exports.ReferenceType = ReferenceType = {}));
+/** Reverse mapping of the reference types so you can get the name from the bitmask (useful for debugging) */
 exports.ReferenceTypeReverseMapping = new Map(Object.entries(ReferenceType).map(([k, v]) => [v, k]));
 /**
  * Check if the reference types have an overlapping type!

package/dataflow/environments/resolve-by-name.d.ts

@@ -13,3 +13,8 @@ import { ReferenceType } from './identifier';
  */
 export declare function resolveByName(name: Identifier, environment: REnvironmentInformation, target?: ReferenceType): IdentifierDefinition[] | undefined;
 export declare function resolvesToBuiltInConstant(name: Identifier | undefined, environment: REnvironmentInformation, wantedValue: unknown): Ternary;
+export interface ResolveResult<T = unknown> {
+    value: T;
+    from: ReferenceType;
+}
+export declare function resolveToConstants(name: Identifier | undefined, environment: REnvironmentInformation): ResolveResult[] | undefined;

package/dataflow/environments/resolve-by-name.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveByName = resolveByName;
 exports.resolvesToBuiltInConstant = resolvesToBuiltInConstant;
+exports.resolveToConstants = resolveToConstants;
 const environment_1 = require("./environment");
 const identifier_1 = require("./identifier");
 const info_1 = require("../info");
@@ -80,4 +81,17 @@ function resolvesToBuiltInConstant(name, environment, wantedValue) {
         return some ? 1 /* Ternary.Maybe */ : 2 /* Ternary.Never */;
     }
 }
+function resolveToConstants(name, environment) {
+    if (name === undefined) {
+        return undefined;
+    }
+    const definitions = resolveByName(name, environment, identifier_1.ReferenceType.Constant);
+    if (definitions === undefined) {
+        return undefined;
+    }
+    return definitions.map(def => ({
+        value: def.value,
+        from: def.type
+    }));
+}
 //# sourceMappingURL=resolve-by-name.js.map

package/dataflow/extractor.js

@@ -20,6 +20,7 @@ const built_in_source_1 = require("./internal/process/functions/call/built-in/bu
 const cfg_1 = require("../util/cfg/cfg");
 const edge_1 = require("./graph/edge");
 const identify_link_to_last_call_relation_1 = require("../queries/catalog/call-context-query/identify-link-to-last-call-relation");
+const built_in_function_definition_1 = require("./internal/process/functions/call/built-in/built-in-function-definition");
 exports.processors = {
     [type_1.RType.Number]: process_value_1.processValue,
     [type_1.RType.String]: process_value_1.processValue,
@@ -56,11 +57,9 @@ function resolveLinkToSideEffects(ast, graph) {
         if (typeof s !== 'object') {
             continue;
         }
-        if (!cfg) {
-            cfg = (0, cfg_1.extractCFG)(ast).graph;
-        }
+        cfg ??= (0, cfg_1.extractCFG)(ast).graph;
         /* this has to change whenever we add a new link to relations because we currently offer no abstraction for the type */
-        const potentials = (0, identify_link_to_last_call_relation_1.identifyLinkToLastCallRelation)(s.id, cfg, graph, s.linkTo.callName);
+        const potentials = (0, identify_link_to_last_call_relation_1.identifyLinkToLastCallRelation)(s.id, cfg, graph, s.linkTo);
         for (const pot of potentials) {
             graph.addEdge(s.id, pot, edge_1.EdgeType.Reads);
         }
@@ -92,6 +91,8 @@ function produceDataFlowGraph(request, ast) {
             df = (0, built_in_source_1.standaloneSourceFile)(request[i], dfData, `root-${i}`, df);
         }
     }
+    // finally, resolve linkages
+    (0, built_in_function_definition_1.updateNestedFunctionCalls)(df.graph, df.environment);
     resolveLinkToSideEffects(ast, df.graph);
     return df;
 }

package/dataflow/graph/dataflowgraph-builder.d.ts

@@ -114,6 +114,12 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      * @see reads for parameters.
      */
     definesOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this;
+    /**
+     * Adds a **defined-by-on-call edge** with from as definition, and to as variable.
+     *
+     * @see reads for parameters.
+     */
+    definedByOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds an **argument edge** (E9) with from as function call, and to as argument.
      *

package/dataflow/graph/dataflowgraph-builder.js

@@ -212,6 +212,14 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     definesOnCall(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.DefinesOnCall);
     }
+    /**
+     * Adds a **defined-by-on-call edge** with from as definition, and to as variable.
+     *
+     * @see reads for parameters.
+     */
+    definedByOnCall(from, to) {
+        return this.edgeHelper(from, to, edge_1.EdgeType.DefinedByOnCall);
+    }
     /**
      * Adds an **argument edge** (E9) with from as function call, and to as argument.
      *

package/dataflow/graph/edge.d.ts

@@ -19,9 +19,15 @@ export declare enum EdgeType {
     Calls = 4,
     /** The source returns target on call */
     Returns = 8,
-    /** The edge determines that source (probably argument) defines the target (probably parameter), currently automatically created by `addEdge` */
+    /**
+     * The edge determines that source (probably argument) defines the target (probably parameter).
+     * This may also link a function call to definitions it causes to be active (as part of the closure) of the called function definition.
+     */
     DefinesOnCall = 16,
-    /** Inverse of `defines-on-call` currently only needed to get better results when slicing complex function calls */
+    /**
+     * Usually the inverse of `defines-on-call` (in the context of arguments and parameters).
+     * This may also link an open read (within a function) to the definition that is active at the call site.
+     */
     DefinedByOnCall = 32,
     /** Formal used as argument to a function call */
     Argument = 64,
@@ -57,8 +63,8 @@ export declare const enum TraverseEdge {
     Never = 0,
     /** Traverse the edge as a side effect */
     SideEffect = 1,
-    /** Traverse this edge if the definition is relevant */
-    DefinedByOnCall = 2,
+    /** Traverse this edge if the definition is relevant (i.e., if two matching edges trigger this state) */
+    OnlyIfBoth = 2,
     /** Always traverse this edge */
     Always = 3
 }

package/dataflow/graph/edge.js

@@ -22,9 +22,15 @@ var EdgeType;
     EdgeType[EdgeType["Calls"] = 4] = "Calls";
     /** The source returns target on call */
     EdgeType[EdgeType["Returns"] = 8] = "Returns";
-    /** The edge determines that source (probably argument) defines the target (probably parameter), currently automatically created by `addEdge` */
+    /**
+     * The edge determines that source (probably argument) defines the target (probably parameter).
+     * This may also link a function call to definitions it causes to be active (as part of the closure) of the called function definition.
+     */
     EdgeType[EdgeType["DefinesOnCall"] = 16] = "DefinesOnCall";
-    /** Inverse of `defines-on-call` currently only needed to get better results when slicing complex function calls */
+    /**
+     * Usually the inverse of `defines-on-call` (in the context of arguments and parameters).
+     * This may also link an open read (within a function) to the definition that is active at the call site.
+     */
     EdgeType[EdgeType["DefinedByOnCall"] = 32] = "DefinedByOnCall";
     /** Formal used as argument to a function call */
     EdgeType[EdgeType["Argument"] = 64] = "Argument";
@@ -89,13 +95,14 @@ function edgeIncludesType(type, types) {
 function edgeDoesNotIncludeType(type, types) {
     return (types & type) === 0;
 }
-const alwaysTraverseEdgeTypes = EdgeType.Reads | EdgeType.DefinedBy | EdgeType.Argument | EdgeType.Calls | EdgeType.DefinesOnCall;
+const alwaysTraverseEdgeTypes = EdgeType.Reads | EdgeType.DefinedBy | EdgeType.Argument | EdgeType.Calls;
+const definedByOnCallTypes = EdgeType.DefinesOnCall | EdgeType.DefinedByOnCall;
 function shouldTraverseEdge(types) {
     if (edgeIncludesType(types, alwaysTraverseEdgeTypes)) {
         return 3 /* TraverseEdge.Always */;
     }
-    else if (edgeIncludesType(types, EdgeType.DefinedByOnCall)) {
-        return 2 /* TraverseEdge.DefinedByOnCall */;
+    else if (edgeIncludesType(types, definedByOnCallTypes)) {
+        return 2 /* TraverseEdge.OnlyIfBoth */;
     }
     else if (edgeIncludesType(types, EdgeType.SideEffectOnCall)) {
         return 1 /* TraverseEdge.SideEffect */;

package/dataflow/graph/graph.d.ts

@@ -1,5 +1,4 @@
-import type { DataflowGraphEdge } from './edge';
-import { EdgeType } from './edge';
+import type { DataflowGraphEdge, EdgeType } from './edge';
 import type { DataflowInformation } from '../info';
 import type { DataflowGraphVertexArgument, DataflowGraphVertexFunctionCall, DataflowGraphVertexInfo } from './vertex';
 import { EmptyArgument } from '../../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
@@ -7,30 +6,56 @@ import type { IdentifierDefinition, IdentifierReference } from '../environments/
 import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { AstIdMap } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { LinkTo } from '../../queries/catalog/call-context-query/call-context-query-format';
+/**
+ * Describes the information we store per function body.
+ * The {@link DataflowFunctionFlowInformation#exitPoints} are stored within the enclosing {@link DataflowGraphVertexFunctionDefinition} vertex.
+ */
 export type DataflowFunctionFlowInformation = Omit<DataflowInformation, 'graph' | 'exitPoints'> & {
     graph: Set<NodeId>;
 };
 /**
+ * A reference with a name, e.g. `a` and `b` in the following function call:
+ *
  * ```r
  * foo(a = 3, b = 2)
  * ```
+ *
+ * @see #isNamedArgument
+ * @see PositionalFunctionArgument
  */
 export interface NamedFunctionArgument extends IdentifierReference {
     readonly name: string;
 }
 /**
+ * A reference which does not have a name, like the references to the arguments `3` and `2` in the following:
+ *
  * ```r
  * foo(3, 2)
  * ```
+ *
+ * @see #isPositionalArgument
+ * @see NamedFunctionArgument
  */
 export interface PositionalFunctionArgument extends Omit<IdentifierReference, 'name'> {
     readonly name?: undefined;
 }
 /** Summarizes either named (`foo(a = 3, b = 2)`), unnamed (`foo(3, 2)`), or empty (`foo(,)`) arguments within a function. */
 export type FunctionArgument = NamedFunctionArgument | PositionalFunctionArgument | typeof EmptyArgument;
+/**
+ * Check if the given argument is a {@link PositionalFunctionArgument}.
+ */
 export declare function isPositionalArgument(arg: FunctionArgument): arg is PositionalFunctionArgument;
+/**
+ * Check if the given argument is a {@link NamedFunctionArgument}.
+ */
 export declare function isNamedArgument(arg: FunctionArgument): arg is NamedFunctionArgument;
+/**
+ * Returns the reference of a non-empty argument.
+ */
 export declare function getReferenceOfArgument(arg: FunctionArgument): NodeId | undefined;
+/**
+ * A reference that is enough to indicate start and end points of an edge within the dataflow graph.
+ */
 type ReferenceForEdge = Pick<IdentifierReference, 'nodeId' | 'controlDependencies'> | IdentifierDefinition;
 /**
  * Maps the edges target to the edge information
@@ -41,11 +66,20 @@ export type OutgoingEdges<Edge extends DataflowGraphEdge = DataflowGraphEdge> =
  * In other words, it maps the source to the edge information.
  */
 export type IngoingEdges<Edge extends DataflowGraphEdge = DataflowGraphEdge> = Map<NodeId, Edge>;
+/**
+ * The structure of the serialized {@link DataflowGraph}.
+ */
 export interface DataflowGraphJson {
     readonly rootVertices: NodeId[];
     readonly vertexInformation: [NodeId, DataflowGraphVertexInfo][];
     readonly edgeInformation: [NodeId, [NodeId, DataflowGraphEdge][]][];
 }
+/**
+ * An unknown side effect describes something that we cannot handle correctly (in all cases).
+ * For example, `eval` will be marked as an unknown side effect as we have no idea of how it will affect the program.
+ * Linked side effects are used whenever we know that a call may be affected by another one in a way that we cannot
+ * grasp from the dataflow perspective (e.g., an indirect dependency based on the currently active graphic device).
+ */
 export type UnknownSidEffect = NodeId | {
     id: NodeId;
     linkTo: LinkTo<RegExp>;
@@ -60,6 +94,11 @@ export type UnknownSidEffect = NodeId | {
  * However, this does not have to hold during the construction as edges may point from or to vertices which are yet to be constructed.
  *
  * All methods return the modified graph to allow for chaining.
+ *
+ * @see {@link DataflowGraph#addEdge|`addEdge`} - to add an edge to the graph
+ * @see {@link DataflowGraph#addVertex|`addVertex`} - to add a vertex to the graph
+ * @see {@link DataflowGraph#fromJson|`fromJson`} - to construct a dataflow graph object from a deserialized JSON object.
+ * @see {@link emptyGraph} - to create an empty graph (useful in tests)
  */
 export declare class DataflowGraph<Vertex extends DataflowGraphVertexInfo = DataflowGraphVertexInfo, Edge extends DataflowGraphEdge = DataflowGraphEdge> {
     private static DEFAULT_ENVIRONMENT;
@@ -144,7 +183,6 @@ export declare class DataflowGraph<Vertex extends DataflowGraphVertexInfo = Data
     addEdge(from: ReferenceForEdge, to: ReferenceForEdge, type: EdgeType): this;
     /** {@inheritDoc} */
     addEdge(from: NodeId | ReferenceForEdge, to: NodeId | ReferenceForEdge, type: EdgeType): this;
-    private installEdge;
     /**
      * Merges the other graph into *this* one (in-place). The return value is only for convenience.
      *