[chore] some code comments

Author: dummdidumm

src/block.js

@@ -1,9 +1,14 @@
 import { get_offsets, dedent_code } from './utils.js';
 
-// return a new block
+// create a new block to add code transformations to
 export const new_block = () => ({ transformed_code: '', line_offsets: null, translations: new Map() });
 
 // get translation info and include the processed scripts in this block's transformed_code
+// each translation consists of info about the original text range (range),
+// the difference after dedenting (dedent), line/length info about the text itself (offsets),
+// line/length info about the transformed code prior to adding the text (unoffsets) and the new
+// line count of the transformed code after adding the text (end). This information can be used
+// to map code back to its original position.
 export const get_translation = (text, block, node, options = {}) => {
 	block.transformed_code += '\n';
 	const translation = { options, unoffsets: get_offsets(block.transformed_code) };

src/postprocess.js

@@ -15,6 +15,7 @@ const transform_message = ({ transformed_code }, { unoffsets, dedent, offsets, r
 		}
 	}
 	// shift position reference backward according to unoffsets
+	// (aka: throw out the generated code lines prior to the original code)
 	{
 		const { length, lines, last } = unoffsets;
 		if (message.line === lines) {
@@ -33,6 +34,7 @@ const transform_message = ({ transformed_code }, { unoffsets, dedent, offsets, r
 		}
 	}
 	// adjust position reference according to the previous dedenting
+	// (aka: re-add the stripped indentation)
 	{
 		const { offsets, total_offsets } = dedent;
 		message.column += offsets[message.line - 1];
@@ -45,6 +47,7 @@ const transform_message = ({ transformed_code }, { unoffsets, dedent, offsets, r
 		}
 	}
 	// shift position reference forward according to offsets
+	// (aka: re-add the code that is originally prior to the code)
 	{
 		const { length, lines, last } = offsets;
 		if (message.line === 1) {