[toolchains] add more detailed typings & comments

conda/js/src/components/toolchain/ToolchainEditor.jsx

@@ -68,8 +68,13 @@ type Props = {
 	saveFunc: (BeatObject) => any,
 };
 
+// represents a timeline of state changes
+// the current state sits between the paste & future states
+// enables very fast redo/undo
 type History = {
+	// past states
 	past: BeatObject[],
+	// future states
 	future: BeatObject[],
 };
 
@@ -77,18 +82,25 @@ type State = {
 	// unsaved changes
 	cache: any,
 	// info for the modal for editing blocks
+	// if the fields are undefined, the modal shouldnt be up
 	modalBlockInfo: {
+		// navigating to a specific block in the JSON
+		// requires a set and a name
 		set: ?BlockSet,
 		name: ?string,
 		active: boolean,
 	},
 	// the clipboard for copy/pasting blocks
 	clipboard?: BlockType[],
+	// is the object insertion modal active?
 	insertModalActive: boolean,
+	// is the modal for renaming groups active?
 	renameGroupModalInfo: ?string,
+	// the current history for the editor
 	history: History,
 };
 
+// generates a new history object whenever the user does an action that changes state
 const generateNewHistory = (state: State): History => {
 	return {
 		past: [
@@ -120,6 +132,7 @@ export class ToolchainEditor extends React.PureComponent<Props, State> {
 		},
 	}
 
+	// if the toolchain was updated, reset specific state fields
 	componentWillReceiveProps = (nextProps: Props) => {
 		this.setState({
 			cache: getValidObj(nextProps.data),
@@ -144,6 +157,7 @@ export class ToolchainEditor extends React.PureComponent<Props, State> {
 		}));
 	}
 
+	// helper to set the groups (this.state.cache.extraContents.groups)
 	setGroups = (groups: Group[]) => {
 		this.setState((prevState, props) => ({
 			cache: {
@@ -157,6 +171,8 @@ export class ToolchainEditor extends React.PureComponent<Props, State> {
 		}));
 	}
 
+	// undoes history by saving the current state to the future
+	// and switching to the latest history state
 	undoHistory = () => {
 		this.setState((prevState) => {
 			if(prevState.history.past.length === 0)
@@ -174,6 +190,8 @@ export class ToolchainEditor extends React.PureComponent<Props, State> {
 		});
 	};
 
+	// redoes history by putting the current state in the past
+	// and switching to the earliest future state
 	redoHistory = () => {
 		this.setState((prevState) => {
 			if(prevState.history.future.length === 0)
@@ -191,18 +209,23 @@ export class ToolchainEditor extends React.PureComponent<Props, State> {
 		});
 	};
 
+	// toggles whether the object insert modal is active or not
 	toggleInsertModal = () => {
 		this.setState((prevState) => ({ insertModalActive: !prevState.insertModalActive }));
 	}
 
+	// toggles whether the group rename modal is active or not
 	toggleRenameGroupModal = (val: ?string) => {
 		this.setState((prevState) => ({ renameGroupModalInfo: val }));
 	}
 
+	// renames a group from an old name to a new one
 	renameGroup = (oldName: string, newName: string) => {
 		this.setGroups(this.state.cache.extraContents.groups.map(g => g.name === oldName ? {...g, name: newName} : g));
 	}
 
+	// finds a block by name from the three block sub-arrays:
+	// blocks (normal blocks), datasets (dataset blocks), analyzers (analyzer blocks)
 	findBlock = (name: string): BlockType => {
 		const b = this.state.cache.contents.blocks.find(b => b.name === name) ||
 			this.state.cache.contents.datasets.find(b => b.name === name) ||
@@ -394,7 +417,12 @@ export class ToolchainEditor extends React.PureComponent<Props, State> {
 		this.setContents(newContents);
 	}
 
-	generateNewBlockData = (blockName: string, set: BlockSet, x: number, y: number, copyBlock?: BlockType) => {
+	// helper func for addBlocks()
+	// generates all the new data necessary for a new block,
+	// including the representation (location & dimensions),
+	// the channel color,
+	// and an initial block object
+	generateNewBlockData = (blockName: string, set: BlockSet, x: number, y: number, copyBlock?: ?BlockType) => {
 		let newBlock = copyBlock ? { ...copyBlock } : undefined;
 		if(newBlock === undefined){
 			newBlock = {};
@@ -425,9 +453,14 @@ export class ToolchainEditor extends React.PureComponent<Props, State> {
 	}
 
 	// adds new blocks at a certain location via an array of arrays of info about the new block(s)
-	// optionally can pass a block to copy
-	// signature of each subarray: blockName: string, set: BlockSet, x: number, y: number, copyBlock?: BlockType
-	addBlocks = (blockData: any[]) => {
+	// each array is info about a new block:
+	// 	- the first string is the new name
+	// 	- the BlockSet is the set to put the block in
+	// 	- the numbers are the x & y coords of the new block
+	// 	- the last entry is an optional block object to copy from
+	// it will also copy connections via looking for connections between copied blocks
+	// and copying them to the related new blocks
+	addBlocks = (blockData: [string, BlockSet, number, number, ?BlockType][]) => {
 		const newBlocks = blockData.map(d => this.generateNewBlockData(...d));
 		const sets = blockData.map(b => b[1]);
 
@@ -496,6 +529,7 @@ export class ToolchainEditor extends React.PureComponent<Props, State> {
 
 	// deletes a block from the toolchain,
 	// as well as any connections to/from it
+	// if it was the sole member of a group, deletes the group too
 	deleteBlocks = (names: string[]) => {
 		const rep = jsonClone(this.state.cache.contents.representation);
 
@@ -548,6 +582,7 @@ export class ToolchainEditor extends React.PureComponent<Props, State> {
 	}
 
 	// deletes a connection
+	// looks at the representation object and the connections array
 	deleteConnection = (cn: ConnectionType) => {
 		const rep = {...this.state.cache.contents.representation};
 
@@ -795,6 +830,8 @@ export class ToolchainEditor extends React.PureComponent<Props, State> {
 		}
 	}
 
+	// gets all the used names in the toolchain:
+	// group names & block names
 	getUsedNames = (): string[] => [
 		...this.state.cache.extraContents.groups.map(g => g.name),
 		...Object.keys(this.state.cache.contents.representation.blocks)