sprinkle some extra comments

Author: inferrinizzard

src/core/Formatter.ts

@@ -105,6 +105,7 @@ export default class Formatter {
 		const lines = query.split('\n');
 		let newQuery: string[] = [];
 		for (let i = 0; i < lines.length; i++) {
+			// if line has trailing comma
 			if (lines[i].match(/.*,$/)) {
 				let commaLines = [lines[i]];
 				// find all lines in comma-bound clause, + 1
@@ -113,8 +114,9 @@ export default class Formatter {
 				}
 
 				if (this.cfg.commaPosition === CommaPosition.tabular) {
-					commaLines = commaLines.map(commaLine => commaLine.replace(/,$/, ''));
+					commaLines = commaLines.map(commaLine => commaLine.replace(/,$/, '')); // trim all trailing commas
 					const commaMaxLength = maxLength(commaLines); // get longest for alignment
+					// make all lines the same length by appending spaces before comma
 					commaLines = commaLines.map((commaLine, j) =>
 						j < commaLines.length - 1 // do not add comma for last item
 							? commaLine + ' '.repeat(commaMaxLength - commaLine.length) + ','
@@ -183,6 +185,7 @@ export default class Formatter {
 				const aliasMaxLength = maxLength(
 					splitLines.map(({ precedingText }) => precedingText.replace(/\s*,\s*$/, '')) // get longest of precedingText, trim trailing comma for non-alias columns
 				);
+				// re-construct line, aligning by inserting space before AS or alias
 				aliasLines = splitLines.map(
 					({ precedingText, as, alias }) =>
 						precedingText +
@@ -208,13 +211,14 @@ export default class Formatter {
 		for (this.index = 0; this.index < this.tokens.length; this.index++) {
 			let token = this.tokenOverride(this.tokens[this.index]);
 
+			// if token is a Reserved Keyword, Command, Binary Command, Dependent Clause, Logical Operator
 			if (isReserved(token)) {
 				this.previousReservedToken = token;
 				if (token.type !== TokenType.RESERVED_KEYWORD) {
-					token = this.tenSpacedToken(token);
+					token = this.tenSpacedToken(token); // convert Reserved Command or Logical Operator to tenSpace format if needed
 				}
 				if (token.type === TokenType.RESERVED_COMMAND) {
-					this.withinSelect = isToken.SELECT(token);
+					this.withinSelect = isToken.SELECT(token); // set withinSelect flag if entering a SELECT clause, else reset
 				}
 			}
 
@@ -246,7 +250,7 @@ export default class Formatter {
 				formattedQuery = this.formatWord(token, formattedQuery);
 			}
 		}
-		return formattedQuery.replace(new RegExp(ZWS, 'ugim'), ' ');
+		return formattedQuery.replace(new RegExp(ZWS, 'ugim'), ' '); // replace all ZWS with whitespace for TenSpace formats
 	}
 
 	/**
@@ -316,8 +320,9 @@ export default class Formatter {
 	 * @return {boolean} Whether or not a newline should be inserted
 	 */
 	checkNewline(index: number): boolean {
-		const tail = this.tokens.slice(index + 1);
+		const tail = this.tokens.slice(index + 1); // get all tokens after current token
 		const nextTokens = tail.slice(
+			// get all tokens between current token and next Reserved Command or query end
 			0,
 			tail.length
 				? tail.findIndex(
@@ -395,15 +400,17 @@ export default class Formatter {
 
 		query = this.addNewline(query);
 
+		// indent TenSpace formats, except when preceding a (
 		if (this.cfg.tenSpace) {
 			if (this.tokenLookAhead()?.value !== '(') {
 				this.indentation.increaseTopLevel();
 			}
+			// indent standard format, except when is [FROM] (
 		} else if (!(this.tokenLookAhead()?.value === '(' && isToken.FROM(token))) {
 			this.indentation.increaseTopLevel();
 		}
 
-		query += this.equalizeWhitespace(this.show(token));
+		query += this.equalizeWhitespace(this.show(token)); // print token onto query
 		if (this.currentNewline && !this.cfg.tenSpace) {
 			query = this.addNewline(query);
 		} else {
@@ -418,7 +425,7 @@ export default class Formatter {
 	 * @param {string} query - formatted query so far
 	 */
 	formatBinaryCommand(token: Token, query: string): string {
-		const isJoin = /JOIN/i.test(token.value);
+		const isJoin = /JOIN/i.test(token.value); // check if token contains JOIN
 		if (!isJoin || this.cfg.tenSpace) {
 			// decrease for boolean set operators or in tenSpace modes
 			this.indentation.decreaseTopLevel();
@@ -490,6 +497,7 @@ export default class Formatter {
 	 * @param {string} query - formatted query so far
 	 */
 	formatLogicalOperator(token: Token, query: string): string {
+		// ignore AND when BETWEEN x [AND] y
 		if (isToken.AND(token) && isToken.BETWEEN(this.tokenLookBehind(2))) {
 			return this.formatWithSpaces(token, query);
 		}
@@ -637,6 +645,8 @@ export default class Formatter {
 	formatQuerySeparator(token: Token, query: string): string {
 		this.indentation.resetIndentation();
 		query = trimSpacesEnd(query);
+
+		// move delimiter to new line if specified
 		if (this.cfg.semicolonNewline) {
 			query += '\n';
 			if (this.cfg.tenSpace) {

src/core/Tokenizer.ts

@@ -168,15 +168,18 @@ export default class Tokenizer {
 	 */
 	getPlaceholderToken(input: string): Token | undefined {
 		const placeholderTokenRegexMap: { regex: RegExp; parseKey: (s: string) => string }[] = [
+			// pattern for placeholder with identifier name
 			{
 				regex: this.IDENT_NAMED_PLACEHOLDER_REGEX ?? NULL_REGEX,
 				parseKey: v => v.slice(1),
 			},
+			// pattern for placeholder with string name
 			{
 				regex: this.STRING_NAMED_PLACEHOLDER_REGEX ?? NULL_REGEX,
 				parseKey: v =>
 					this.getEscapedPlaceholderKey({ key: v.slice(2, -1), quoteChar: v.slice(-1) }),
 			},
+			// pattern for placeholder with numeric index
 			{
 				regex: this.INDEXED_PLACEHOLDER_REGEX ?? NULL_REGEX,
 				parseKey: v => v.slice(1),
@@ -204,6 +207,7 @@ export default class Tokenizer {
 			return undefined;
 		}
 
+		// prioritised list of Reserved token types
 		const reservedTokenList = [
 			TokenType.RESERVED_COMMAND,
 			TokenType.RESERVED_BINARY_COMMAND,

vscode/src/extension.ts

@@ -14,17 +14,18 @@ const getConfigs = (
 	language: FormatterLanguage
 ) => {
 	const ignoreTabSettings = settings.get<boolean>('ignoreTabSettings');
-	const { tabSize, insertSpaces } = ignoreTabSettings
+	const { tabSize, insertSpaces } = ignoreTabSettings // override tab settings if ignoreTabSettings is true
 		? {
 				tabSize: settings.get<number>('tabSizeOverride')!,
 				insertSpaces: settings.get<boolean>('insertSpacesOverride')!,
 		  }
 		: formattingOptions;
 	const indent = insertSpaces ? ' '.repeat(tabSize) : '\t';
 
+	// build format configs from settings
 	const formatConfigs = {
 		language:
-			language === 'sql'
+			language === 'sql' // override default SQL language mode if SQLFlavourOverride is set
 				? settings.get<FormatterLanguage>('SQLFlavourOverride') ?? 'sql'
 				: language,
 		indent,
@@ -36,7 +37,7 @@ const getConfigs = (
 		commaPosition: settings.get<CommaPosition>('commaPosition'),
 		newline: (newlineSetting =>
 			newlineSetting === 'itemCount'
-				? settings.get<number>('itemCount')
+				? settings.get<number>('itemCount') // pass itemCount number if keywordNewline is itemCount mode
 				: (newlineSetting as NewlineMode))(settings.get<string>('keywordNewline')),
 		parenOptions: {
 			openParenNewline: settings.get<boolean>('parenOptions.openParenNewline'),
@@ -60,6 +61,7 @@ export function activate(context: vscode.ExtensionContext) {
 			const settings = vscode.workspace.getConfiguration('Prettier-SQL');
 			const formatConfigs = getConfigs(settings, options, language);
 
+			// extract all lines from document
 			const lines = [...new Array(document.lineCount)].map((_, i) => document.lineAt(i).text);
 			let text;
 			try {
@@ -69,6 +71,7 @@ export function activate(context: vscode.ExtensionContext) {
 				return [];
 			}
 
+			// replace document with formatted text
 			return [
 				vscode.TextEdit.replace(
 					new vscode.Range(
@@ -90,6 +93,7 @@ export function activate(context: vscode.ExtensionContext) {
 		'hive-sql': 'sql',
 		'sql-bigquery': 'bigquery',
 	};
+	// add Prettier-SQL as a format provider for each language
 	Object.entries(languages).forEach(([vscodeLang, prettierLang]) =>
 		context.subscriptions.push(
 			vscode.languages.registerDocumentFormattingEditProvider(
@@ -107,6 +111,7 @@ export function activate(context: vscode.ExtensionContext) {
 
 			const settings = vscode.workspace.getConfiguration('Prettier-SQL');
 
+			// get tab settings from workspace
 			const workspaceConfig = vscode.workspace.getConfiguration('editor');
 			const tabOptions = {
 				tabSize: workspaceConfig.get<number>('tabSize')!,
@@ -117,6 +122,7 @@ export function activate(context: vscode.ExtensionContext) {
 
 			const editor = vscode.window.activeTextEditor;
 			try {
+				// format and replace each selection
 				editor?.edit(editBuilder => {
 					editor.selections.forEach(sel =>
 						editBuilder.replace(sel, format(editor.document.getText(sel), formatConfigs))