prettier-plugin-wolfram 0.7.9 → 0.7.11

package/README.md

@@ -129,6 +129,7 @@ Typical `.prettierrc` example:
 		"alignRuleValues": false,
 		"documentationCommentColumn": 0,
 		"documentationCommentPadding": 2,
+		"documentationCommentMarkers": false,
 		"topLevelSpacingMode": "declarations",
 		"preserveTildeInfixFunctions": "",
 		"moduleVarsBreakThreshold": 40,
@@ -158,6 +159,7 @@ this plugin.
 | `wolfram.alignRuleValues`                             | boolean     | `false`                             | Vertically aligns `Rule` and `RuleDelayed` values in multiline argument, list, and association layouts. |
 | `wolfram.documentationCommentColumn`                  | integer     | `0`                                 | Column for trailing documentation comments. `0` computes a column per contiguous block. |
 | `wolfram.documentationCommentPadding`                 | integer     | `2`                                 | Minimum spaces between code and an aligned trailing documentation comment when the column is computed automatically. |
+| `wolfram.documentationCommentMarkers`                 | boolean     | `false`                             | Treats trailing comments beginning with `<` as documentation comments aligned at `printWidth`. |
 | `wolfram.topLevelSpacingMode`                         | string      | `"declarations"`                    | Top-level blank-line policy. Allowed values are `declarations`, `all`, and `none`. |
 | `wolfram.preserveTildeInfixFunctions`                 | string      | `""`                                | Comma-separated function names that stay in `x ~ f ~ y` form instead of normalizing to `f[x, y]`. |
 | `wolfram.moduleVarsBreakThreshold`                    | integer     | `40`                                | Character count at which block-structure variable lists break across lines. |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "prettier-plugin-wolfram",
-	"version": "0.7.9",
+	"version": "0.7.11",
 	"description": "Prettier plugin for Wolfram Language using tree-sitter",
 	"license": "MIT",
 	"repository": {

package/src/options.js

@@ -109,6 +109,13 @@ export const wolframOptions = {
 		description:
 			"Minimum spaces between code and an aligned trailing documentation comment in auto mode.",
 	},
+	documentationCommentMarkers: {
+		type: "boolean",
+		default: false,
+		legacyName: "wolframDocumentationCommentMarkers",
+		description:
+			"Treat trailing comments beginning with < as documentation comments aligned at printWidth.",
+	},
 	topLevelSpacingMode: {
 		type: "string",
 		default: "declarations",

package/src/translator/docComments.js

@@ -1,6 +1,7 @@
 import { doc } from "prettier";
 import { normalizeWolframOptions } from "../options.js";
 import { sameLineCommentSeparator } from "./commentSpacing.js";
+import { sourceLineGap } from "./sourceLines.js";
 
 export function joinDocsWithSpace(docs) {
 	const nonEmptyDocs = docs.filter(
@@ -19,7 +20,15 @@ export function isDocumentationCommentMarkerText(text) {
 	return /^\(\*\s*</u.test(String(text ?? ""));
 }
 
-export function hasDocumentationCommentMarker(comment) {
+function documentationCommentMarkersEnabled(options) {
+	return (
+		normalizeWolframOptions(options).wolframDocumentationCommentMarkers ===
+		true
+	);
+}
+
+export function hasDocumentationCommentMarker(comment, options) {
+	if (!documentationCommentMarkersEnabled(options)) return false;
 	const node = comment?.node ?? comment;
 	return (
 		node?.kind === "Token`Comment" &&
@@ -27,6 +36,25 @@ export function hasDocumentationCommentMarker(comment) {
 	);
 }
 
+function hasMarkedDocumentationCommentEntry(entry, options) {
+	return (entry?.trailingComments ?? []).some((comment) =>
+		hasDocumentationCommentMarker(comment, options),
+	);
+}
+
+function isCommaEntry(entry) {
+	return entry?.node?.type === "LeafNode" && entry.node.kind === "Token`Comma";
+}
+
+function canAttachMarkedTrailingComment(previousEntry, commentEntry, options) {
+	return (
+		previousEntry &&
+		!isCommaEntry(previousEntry) &&
+		hasDocumentationCommentMarker(commentEntry, options) &&
+		sourceLineGap(previousEntry.node, commentEntry.node, options) === 0
+	);
+}
+
 function normalizeDocumentationCommentMarker(text) {
 	return String(text).replace(/^\(\*\s*<\s*/u, "(* < ");
 }
@@ -34,6 +62,7 @@ function normalizeDocumentationCommentMarker(text) {
 function normalizedCommentDoc(comment, options) {
 	const rendered = renderFlatDoc(comment.doc, options);
 	if (
+		!documentationCommentMarkersEnabled(options) ||
 		!isDocumentationCommentMarkerText(rendered) ||
 		rendered.includes("\n")
 	) {
@@ -62,6 +91,30 @@ export function joinCommentDocs(comments, options) {
 	return joined;
 }
 
+export function withMarkedTrailingCommentDocs(entries, options) {
+	const result = [];
+
+	for (const entry of entries) {
+		const previousEntry = result[result.length - 1];
+		if (canAttachMarkedTrailingComment(previousEntry, entry, options)) {
+			previousEntry.trailingComments ??= [];
+			previousEntry.trailingComments.push({
+				node: entry.node,
+				doc: entry.doc,
+			});
+			previousEntry.trailingCommentDoc = joinCommentDocs(
+				previousEntry.trailingComments,
+				options,
+			);
+			continue;
+		}
+
+		result.push(entry);
+	}
+
+	return result;
+}
+
 export function renderFlatDoc(docNode, options) {
 	const rendered = doc.printer.printDocToString(docNode, {
 		printWidth: 100000,
@@ -76,10 +129,18 @@ export function documentationCommentColumn(
 	entries,
 	options,
 	suffixForEntry = () => "",
+	columnOffset = 0,
 ) {
 	options = normalizeWolframOptions(options);
 	const manual = options.wolframDocumentationCommentColumn ?? 0;
-	if (manual > 0) return manual;
+	if (manual > 0) return Math.max(1, manual - columnOffset);
+	if (
+		entries.some((entry) =>
+			hasMarkedDocumentationCommentEntry(entry, options),
+		)
+	) {
+		return Math.max(1, (options.printWidth ?? 80) - columnOffset);
+	}
 	const padding = Math.max(
 		1,
 		options.wolframDocumentationCommentPadding ?? 2,

package/src/translator/nodes/call.js

@@ -1,11 +1,16 @@
 // src/translator/nodes/call.js
 import { doc } from "prettier";
 const { builders } = doc;
-import { isComment, isTrivia } from "./leaf.js";
+import { isComment, isTrivia, stringLineIndentDepth } from "./leaf.js";
 import { alignedRuleDoc, withAlignedRuleValues } from "../ruleAlignment.js";
 import { commentBoundarySeparator } from "../commentSpacing.js";
+import {
+	documentationCommentColumn,
+	withAlignedTrailingComment,
+	withMarkedTrailingCommentDocs,
+} from "../docComments.js";
 import { normalizeWolframOptions } from "../../options.js";
-const { group, indent, softline, line } = builders;
+const { group, indent, softline, line, hardline } = builders;
 
 const BRACKET_KINDS = new Set(["Token`OpenSquare", "Token`CloseSquare"]);
 
@@ -14,7 +19,7 @@ function isBracketToken(node) {
 }
 
 function isCommaToken(node) {
-	return node.type === "LeafNode" && node.kind === "Token`Comma";
+	return node?.type === "LeafNode" && node.kind === "Token`Comma";
 }
 
 function nextContentEntry(entries, startIndex) {
@@ -154,19 +159,48 @@ function printedEntries(path, print, entries) {
 	}));
 }
 
-function sequenceDocs(entries, options, itemKind) {
+function sequenceDocs(rawEntries, options, itemKind, columnOffset = 0) {
+	const entries = withMarkedTrailingCommentDocs(rawEntries, options);
 	const docs = [];
 	const commaGap = options.wolframSpaceAfterComma ? line : softline;
 	const alignmentGroupId = entries.some((entry) => entry.alignedRuleDoc)
 		? Symbol("wolfram-align-rule-values")
 		: null;
+	for (let i = 0; i < entries.length; i++) {
+		if (entries[i].trailingCommentDoc) {
+			entries[i].trailingCommentSuffix = trailingCommentSuffix(
+				entries,
+				i,
+			);
+		}
+	}
+	const trailingCommentEntries = entries.filter(
+		(entry) => entry.trailingCommentDoc,
+	);
+	const trailingCommentColumn =
+		trailingCommentEntries.length > 0
+			? documentationCommentColumn(
+					trailingCommentEntries,
+					options,
+					(entry) => entry.trailingCommentSuffix ?? "",
+					columnOffset,
+				)
+			: null;
 	let previousKind = null;
 
 	for (let i = 0; i < entries.length; i++) {
 		const entry = entries[i];
 		if (isCommaToken(entry.node)) {
-			if (previousKind === null || previousKind === "comma") continue;
 			const previousEntry = previousContentEntry(entries, i);
+			if (
+				previousEntry?.trailingCommentDoc &&
+				previousEntry.trailingCommentSuffix === ","
+			) {
+				previousKind = "comma";
+				continue;
+			}
+
+			if (previousKind === null || previousKind === "comma") continue;
 			const followingEntry = nextContentEntry(entries, i);
 			const separator =
 				followingEntry &&
@@ -192,7 +226,27 @@ function sequenceDocs(entries, options, itemKind) {
 			);
 		}
 
-		docs.push(alignedRuleDoc(entry, alignmentGroupId));
+		const entryDoc = alignedRuleDoc(entry, alignmentGroupId);
+		if (entry.trailingCommentDoc) {
+			docs.push(
+				withAlignedTrailingComment(
+					{ ...entry, doc: entryDoc },
+					options,
+					trailingCommentColumn,
+					entry.trailingCommentSuffix ?? "",
+				),
+			);
+			if (
+				entry.trailingCommentSuffix === "," &&
+				nextContentEntry(entries, i)
+			) {
+				docs.push(hardline);
+				previousKind = "comma";
+				continue;
+			}
+		} else {
+			docs.push(entryDoc);
+		}
 		previousKind = isComment(entry.node) ? "comment" : itemKind;
 	}
 
@@ -205,6 +259,14 @@ function grouped(contents, alignmentGroupId) {
 		: group(contents);
 }
 
+function contentColumnOffset(path, options) {
+	return stringLineIndentDepth(path) * (options.tabWidth ?? 2);
+}
+
+function trailingCommentSuffix(entries, index) {
+	return isCommaToken(entries[index + 1]?.node) ? "," : "";
+}
+
 function printPartCall(path, options, print, node, head) {
 	const partEntry = partGroupEntry(node);
 	if (!partEntry) return null;
@@ -223,7 +285,12 @@ function printPartCall(path, options, print, node, head) {
 
 	if (args.length === 0) return [head, "[[]]"];
 
-	const { docs, alignmentGroupId } = sequenceDocs(entries, options, "part");
+	const { docs, alignmentGroupId } = sequenceDocs(
+		entries,
+		options,
+		"part",
+		contentColumnOffset(path, options),
+	);
 	return grouped(
 		[head, "[[", indent([softline, ...docs]), softline, "]]"],
 		alignmentGroupId,
@@ -246,7 +313,12 @@ export function printCall(path, options, print, node) {
 
 	if (args.length === 0) return [head, "[]"];
 
-	const { docs, alignmentGroupId } = sequenceDocs(entries, options, "arg");
+	const { docs, alignmentGroupId } = sequenceDocs(
+		entries,
+		options,
+		"arg",
+		contentColumnOffset(path, options),
+	);
 	const contents = [head, "[", indent([softline, ...docs]), softline, "]"];
 
 	return grouped(contents, alignmentGroupId);

package/src/translator/nodes/group.js

@@ -1,11 +1,16 @@
 // src/translator/nodes/group.js
 import { doc } from "prettier";
 const { builders } = doc;
-import { isComment, isTrivia } from "./leaf.js";
+import { isComment, isTrivia, stringLineIndentDepth } from "./leaf.js";
 import { alignedRuleDoc, withAlignedRuleValues } from "../ruleAlignment.js";
 import { commentBoundarySeparator } from "../commentSpacing.js";
+import {
+	documentationCommentColumn,
+	withAlignedTrailingComment,
+	withMarkedTrailingCommentDocs,
+} from "../docComments.js";
 import { normalizeWolframOptions } from "../../options.js";
-const { group, indent, softline, line } = builders;
+const { group, indent, softline, line, hardline } = builders;
 
 const GROUP_DELIMITERS = {
 	GroupSquare: ["[", "]"],
@@ -32,7 +37,7 @@ function isBracketToken(node) {
 }
 
 function isCommaToken(node) {
-	return node.type === "LeafNode" && node.kind === "Token`Comma";
+	return node?.type === "LeafNode" && node.kind === "Token`Comma";
 }
 
 function nextContentEntry(entries, startIndex) {
@@ -96,14 +101,25 @@ function sequenceEntries(path, print, node) {
 	}, []);
 }
 
+function contentColumnOffset(path, options) {
+	return stringLineIndentDepth(path) * (options.tabWidth ?? 2);
+}
+
+function trailingCommentSuffix(entries, index) {
+	return isCommaToken(entries[index + 1]?.node) ? "," : "";
+}
+
 export function printGroup(path, options, print, node) {
 	options = normalizeWolframOptions(options);
 	const [open, close] = GROUP_DELIMITERS[node.kind] ?? ["{", "}"];
-	const entries = withAlignedRuleValues(
-		sequenceEntries(path, print, node),
-		path,
+	const entries = withMarkedTrailingCommentDocs(
+		withAlignedRuleValues(
+			sequenceEntries(path, print, node),
+			path,
+			options,
+			print,
+		),
 		options,
-		print,
 	);
 
 	if (entries.length === 0) return `${open}${close}`;
@@ -113,13 +129,41 @@ export function printGroup(path, options, print, node) {
 	const alignmentGroupId = entries.some((entry) => entry.alignedRuleDoc)
 		? Symbol("wolfram-align-rule-values")
 		: null;
+	for (let i = 0; i < entries.length; i++) {
+		if (entries[i].trailingCommentDoc) {
+			entries[i].trailingCommentSuffix = trailingCommentSuffix(
+				entries,
+				i,
+			);
+		}
+	}
+	const trailingCommentEntries = entries.filter(
+		(entry) => entry.trailingCommentDoc,
+	);
+	const trailingCommentColumn =
+		trailingCommentEntries.length > 0
+			? documentationCommentColumn(
+					trailingCommentEntries,
+					options,
+					(entry) => entry.trailingCommentSuffix ?? "",
+					contentColumnOffset(path, options),
+				)
+			: null;
 	let previousKind = null;
 
 	for (let i = 0; i < entries.length; i++) {
 		const entry = entries[i];
 		if (isCommaToken(entry.node)) {
-			if (previousKind === null || previousKind === "comma") continue;
 			const previousEntry = previousContentEntry(entries, i);
+			if (
+				previousEntry?.trailingCommentDoc &&
+				previousEntry.trailingCommentSuffix === ","
+			) {
+				previousKind = "comma";
+				continue;
+			}
+
+			if (previousKind === null || previousKind === "comma") continue;
 			const followingEntry = nextContentEntry(entries, i);
 			const separator =
 				followingEntry &&
@@ -145,7 +189,27 @@ export function printGroup(path, options, print, node) {
 			);
 		}
 
-		docs.push(alignedRuleDoc(entry, alignmentGroupId));
+		const entryDoc = alignedRuleDoc(entry, alignmentGroupId);
+		if (entry.trailingCommentDoc) {
+			docs.push(
+				withAlignedTrailingComment(
+					{ ...entry, doc: entryDoc },
+					options,
+					trailingCommentColumn,
+					entry.trailingCommentSuffix ?? "",
+				),
+			);
+			if (
+				entry.trailingCommentSuffix === "," &&
+				nextContentEntry(entries, i)
+			) {
+				docs.push(hardline);
+				previousKind = "comma";
+				continue;
+			}
+		} else {
+			docs.push(entryDoc);
+		}
 		previousKind = isComment(entry.node) ? "comment" : "item";
 	}
 

package/src/translator/nodes/infix.js

@@ -192,7 +192,9 @@ export function printInfix(node, options, print) {
 			(entry) => entry.trailingCommentDoc,
 		);
 		const hasMarkedDocumentationComment = trailingEntries.some((entry) =>
-			entry.trailingComments.some(hasDocumentationCommentMarker),
+			entry.trailingComments.some((comment) =>
+				hasDocumentationCommentMarker(comment, options),
+			),
 		);
 		const alignTrailingComments =
 			(options.wolframDocumentationCommentColumn ?? 0) > 0 ||