doc(dfg): working on documentation for vertices in the code

src/dataflow/graph/graph.ts

@@ -26,21 +26,35 @@ import { BuiltIn } from '../environments/built-in';
 import { dataflowLogger } from '../logger';
 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
@@ -49,21 +63,33 @@ export interface PositionalFunctionArgument extends Omit<IdentifierReference, 'n
 /** 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 function isPositionalArgument(arg: FunctionArgument): arg is PositionalFunctionArgument {
 	return arg !== EmptyArgument && arg.name === undefined;
 }
 
+/**
+ * Check if the given argument is a {@link NamedFunctionArgument}.
+ */
 export function isNamedArgument(arg: FunctionArgument): arg is NamedFunctionArgument {
 	return arg !== EmptyArgument && arg.name !== undefined;
 }
 
+/**
+ * Returns the reference of a non-empty argument.
+ */
 export function getReferenceOfArgument(arg: FunctionArgument): NodeId | undefined {
 	if(arg !== EmptyArgument) {
 		return arg?.nodeId;
 	}
 	return 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
 
 
@@ -77,13 +103,9 @@ export type OutgoingEdges<Edge extends DataflowGraphEdge = DataflowGraphEdge> =
  */
 export type IngoingEdges<Edge extends DataflowGraphEdge = DataflowGraphEdge> = Map<NodeId, Edge>
 
-
-function extractEdgeIds(from: NodeId | ReferenceForEdge, to: NodeId | ReferenceForEdge): { fromId: NodeId, toId: NodeId } {
-	const fromId = typeof from === 'object' ? from.nodeId : from;
-	const toId = typeof to === 'object' ? to.nodeId : to;
-	return { fromId, toId };
-}
-
+/**
+ * The structure of the serialized {@link DataflowGraph}.
+ */
 export interface DataflowGraphJson {
 	readonly rootVertices:      NodeId[],
 	readonly vertexInformation: [NodeId, DataflowGraphVertexInfo][],
@@ -102,6 +124,7 @@ export type UnknownSidEffect = NodeId | { id: NodeId, linkTo: LinkTo<RegExp> }
  * 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.
+ * You can use {@link DataflowGraph#fromJson} to construct a dataflow graph object from a deserialized JSON object.
  */
 export class DataflowGraph<
 	Vertex extends DataflowGraphVertexInfo = DataflowGraphVertexInfo,
@@ -280,7 +303,7 @@ export class DataflowGraph<
 	 * Please note that this will never make edges to {@link BuiltIn} as they are not part of the graph.
 	 */
 	public addEdge(from: NodeId | ReferenceForEdge, to: NodeId | ReferenceForEdge, type: EdgeType): this {
-		const { fromId, toId } = extractEdgeIds(from, to);
+		const [fromId, toId] = extractEdgeIds(from, to);
 
 		if(fromId === toId || toId === BuiltIn) {
 			return this;
@@ -457,3 +480,12 @@ function mergeNodeInfos<Vertex extends DataflowGraphVertexInfo>(current: Vertex,
 
 	return current;
 }
+
+/**
+ * Returns the ids of the dataflow vertices referenced by a {@link ReferenceForEdge}.
+ */
+function extractEdgeIds(from: NodeId | ReferenceForEdge, to: NodeId | ReferenceForEdge): [fromId: NodeId, toId: NodeId] {
+	const fromId = typeof from === 'object' ? from.nodeId : from;
+	const toId = typeof to === 'object' ? to.nodeId : to;
+	return [fromId, toId];
+}

src/dataflow/graph/vertex.ts

@@ -4,8 +4,6 @@ import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-i
 import type { REnvironmentInformation } from '../environments/environment';
 import type { ControlDependency } from '../info';
 
-export type DataflowGraphVertices<Vertex extends DataflowGraphVertexInfo = DataflowGraphVertexInfo> = Map<NodeId, Vertex>
-
 
 export enum VertexType {
 	Value              = 'value',
@@ -43,10 +41,23 @@ interface DataflowGraphVertexBase extends MergeableRecord {
 
 /**
  * Marker vertex for a value in the dataflow of the program.
+ * This does not contain the _value_ of the referenced constant
+ * as this is available with the {@link DataflowGraphVertexBase#id|id} in the {@link NormalizedAst|normlaized AST}
+ * (or more specifically the {@link AstIdMap}).
+ *
+ * If you have a {@link DataflowGraph|dataflow graph} named `graph`
+ * with an {@link AstIdMap} and a value vertex object with name `value` the following Code should work:
+ *
+ * @example
+ * ```ts
+ * const node = graph.idMap.get(value.id)
+ * ```
+ *
+ * This then returns the corresponding node in the {@link NormalizedAst|normlaized AST}, for example
+ * an {@link RNumber} or {@link RString}.
  */
 export interface DataflowGraphVertexValue extends DataflowGraphVertexBase {
 	readonly tag:          VertexType.Value
-	/* currently without containing the 'real' value as it is part of the normalized AST as well */
 	readonly environment?: undefined
 }
 
@@ -104,9 +115,21 @@ export interface DataflowGraphVertexFunctionDefinition extends DataflowGraphVert
 	environment?: REnvironmentInformation
 }
 
+/**
+ * What is to be passed to construct a vertex in the {@link DataflowGraph|dataflow graph}
+ */
 export type DataflowGraphVertexArgument = DataflowGraphVertexUse | DataflowGraphVertexVariableDefinition | DataflowGraphVertexFunctionDefinition | DataflowGraphVertexFunctionCall | DataflowGraphVertexValue
+
+/**
+ * This is the union type of all possible vertices that appear within a {@link DataflowGraph|dataflow graph},
+ * they can be constructed passing a {@link DataflowGraphVertexArgument} to the graph.
+ *
+ * See {@link DataflowGraphVertices} for an id-based mapping.
+ */
 export type DataflowGraphVertexInfo = Required<DataflowGraphVertexArgument>
 
+export type DataflowGraphVertices<Vertex extends DataflowGraphVertexInfo = DataflowGraphVertexInfo> = Map<NodeId, Vertex>
+
 
 export function isValueVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexValue {
 	return vertex.tag === VertexType.Value;

src/r-bridge/lang-4.x/ast/model/nodes/r-number.ts

@@ -2,7 +2,11 @@ import type { Leaf, Location, NoInfo } from '../model';
 import type { RType } from '../type';
 import type { RNumberValue } from '../../../convert-values';
 
-/** includes numeric, integer, and complex */
+/**
+ * A number like `3`, `-2.14`, `1L`, or `2i`.
+ * Includes numeric, integer, and complex.
+ * See {@link RNumberValue} for more information.
+ */
 export interface RNumber<Info = NoInfo> extends Leaf<Info>, Location {
 	readonly type: RType.Number
 	content:       RNumberValue