prettier-plugin-wolfram 0.7.7 → 0.7.10

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.7",
+	"version": "0.7.10",
 	"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/parser/adapter.js

@@ -288,7 +288,6 @@ function adaptCall(node, ctx, openKind, openText, closeKind, closeText) {
 // The tree-sitter "part" node uses "[[" and "]]" tokens; we split each into two "["/"]" leaves.
 function adaptPart(node, ctx) {
 	const headNode = node.childForFieldName("head");
-	const argsNode = node.childForFieldName("arguments");
 	// Find the "[[" and "]]" anonymous tokens
 	let openDoubleToken = null, closeDoubleToken = null;
 	for (let i = 0; i < node.childCount; i++) {
@@ -309,9 +308,23 @@ function adaptPart(node, ctx) {
 	const outerCloseSrc = [offsetToLineCol(ctx.lineIndex, closeDoubleToken.startIndex + 1), offsetToLineCol(ctx.lineIndex, closeDoubleToken.endIndex)];
 	const innerCloseLeaf = { type: "LeafNode", kind: "Token`CloseSquare", value: "]", source: innerCloseSrc };
 	const outerCloseLeaf = { type: "LeafNode", kind: "Token`CloseSquare", value: "]", source: outerCloseSrc };
-	// Build GroupNode(GroupSquare) wrapping the content
+	// Build GroupNode(GroupSquare) wrapping the content. Iterate the named
+	// children between the delimiters (args + any comment extras) in source
+	// order, injecting whitespace trivia, so comments inside [[...]] survive —
+	// previously only the `arguments` field was read and comments were dropped.
+	const innerOpenEnd = openDoubleToken.startIndex + 1;
+	const innerCloseStart = closeDoubleToken.startIndex;
 	const groupChildren = [innerOpenLeaf];
-	if (argsNode) groupChildren.push(adaptArguments(argsNode, ctx));
+	let lastIdx = innerOpenEnd;
+	for (const c of namedChildren(node)) {
+		if (c === headNode) continue;
+		if (c.startIndex < innerOpenEnd || c.endIndex > innerCloseStart) continue;
+		for (const t of triviaLeaves(lastIdx, c.startIndex, ctx)) groupChildren.push(t);
+		if (c.type === "comment") groupChildren.push(leaf(c, ctx));
+		else groupChildren.push(adaptArguments(c, ctx));
+		lastIdx = c.endIndex;
+	}
+	for (const t of triviaLeaves(lastIdx, innerCloseStart, ctx)) groupChildren.push(t);
 	groupChildren.push(innerCloseLeaf);
 	const groupSrc = [offsetToLineCol(ctx.lineIndex, openDoubleToken.startIndex + 1), offsetToLineCol(ctx.lineIndex, closeDoubleToken.startIndex + 1)];
 	const groupNode = { type: "GroupNode", kind: "GroupSquare", children: groupChildren, source: groupSrc };
@@ -677,29 +690,27 @@ function adaptMessageName(node, ctx) {
 	const tagText = ctx.source.slice(tagStart, tagEnd);
 	const tagSource = [offsetToLineCol(ctx.lineIndex, tagStart), offsetToLineCol(ctx.lineIndex, tagEnd)];
 	const tagLeaf = { type: "LeafNode", kind: "String", value: tagText, source: tagSource };
-	return { type: "InfixNode", op: "MessageName", children: [lhs, colonColonLeaf, tagLeaf], source: nodeSource(node, ctx.lineIndex) };
+	// Preserve any comment that sits between the LHS and "::" (threaded as trivia).
+	const between = triviaLeaves(named[0].endIndex, colonColonToken.startIndex, ctx);
+	return { type: "InfixNode", op: "MessageName", children: [lhs, ...between, colonColonLeaf, tagLeaf], source: nodeSource(node, ctx.lineIndex) };
 }
 
 // get: << expr — emit PrefixNode(Get, [Token`LessLess, expr])
+// Iterate in source order so any comment between "<<" and the operand survives.
 function adaptGet(node, ctx) {
-	const { named, tokens } = parts(node);
-	const opToken = tokens[0];
-	const opLeafNode = { type: "LeafNode", kind: "Token`LessLess", value: "<<", source: nodeSource(opToken, ctx.lineIndex) };
-	return { type: "PrefixNode", op: "Get", children: [opLeafNode, adaptNode(named[0], ctx)], source: nodeSource(node, ctx.lineIndex) };
+	return { type: "PrefixNode", op: "Get", children: adaptChildrenInOrder(node, ctx), source: nodeSource(node, ctx.lineIndex) };
 }
 
 // put: lhs >> rhs or lhs >>> rhs — emit BinaryNode(Put/PutAppend, [lhs, op, rhs])
+// Iterate in source order so comments between operands/operator survive.
 function adaptPut(node, ctx) {
-	const { named, tokens } = parts(node);
-	const opToken = tokens[0];
-	const opText = ctx.source.slice(opToken.startIndex, opToken.endIndex);
+	const { tokens } = parts(node);
+	const opText = ctx.source.slice(tokens[0].startIndex, tokens[0].endIndex);
 	const op = opText === ">>>" ? "PutAppend" : "Put";
-	const kind = opText === ">>>" ? "Token`GreaterGreaterGreater" : "Token`GreaterGreater";
-	const opLeafNode = { type: "LeafNode", kind, value: opText, source: nodeSource(opToken, ctx.lineIndex) };
 	return {
 		type: "BinaryNode",
 		op,
-		children: [adaptNode(named[0], ctx), opLeafNode, adaptNode(named[1], ctx)],
+		children: adaptChildrenInOrder(node, ctx),
 		source: nodeSource(node, ctx.lineIndex),
 	};
 }
@@ -713,44 +724,68 @@ function adaptTildeInfix(node, ctx) {
 
 // span: ;; with optional LHS and RHS
 // Forms: a ;; b, a ;;, ;; b, ;; (bare)
+//
+// Operands are the named children that aren't comments. Comments are named
+// "extras" the grammar threads between the operands; they must be kept in the
+// children (so the printer can preserve them) AND excluded from the operand
+// count — counting a comment as an operand previously matched none of the
+// arity branches and collapsed `a ;; (* c *) b` to the implicit `1 ;; All`.
+// The 3-part form a ;; b ;; c nests as span(a, span(b, c)), so a single span
+// node has at most two operands.
 function adaptSpan(node, ctx) {
-	const named = [], semiSemiTokens = [];
+	const operands = [];
+	let semiSemiToken = null;
 	for (let i = 0; i < node.childCount; i++) {
 		const c = node.child(i);
-		if (c.isNamed) named.push(c);
-		else if (ctx.source.slice(c.startIndex, c.endIndex) === ";;") semiSemiTokens.push(c);
+		if (!c.isNamed) {
+			if (semiSemiToken === null && ctx.source.slice(c.startIndex, c.endIndex) === ";;") {
+				semiSemiToken = c;
+			}
+		} else if (c.type !== "comment") {
+			operands.push(c);
+		}
 	}
-	const semiSemiToken = semiSemiTokens[0];
-	const semiSemiLeaf = { type: "LeafNode", kind: "Token`SemiSemi", value: ";;", source: nodeSource(semiSemiToken, ctx.lineIndex) };
 
-	// Determine LHS and RHS based on what's present
-	// We look at whether the ";;" comes after or before named children by comparing indices
+	// Classify the (at most two) operands as LHS/RHS by position around ";;".
 	let lhsNode = null, rhsNode = null;
-	if (named.length === 2) {
-		// a ;; b
-		lhsNode = named[0];
-		rhsNode = named[1];
-	} else if (named.length === 1) {
-		if (named[0].startIndex < semiSemiToken.startIndex) {
-			// a ;;
-			lhsNode = named[0];
-		} else {
-			// ;; b
-			rhsNode = named[0];
+	if (operands.length >= 2) {
+		lhsNode = operands[0];
+		rhsNode = operands[1];
+	} else if (operands.length === 1) {
+		if (operands[0].startIndex < semiSemiToken.startIndex) lhsNode = operands[0];
+		else rhsNode = operands[0];
+	}
+
+	const implicitBound = (kind, value) => ({
+		type: "LeafNode", kind, value, source: nodeSource(semiSemiToken, ctx.lineIndex),
+	});
+
+	// Emit children in source order, threading comments and whitespace trivia.
+	// Absent operands are filled with the implicit Span bounds (1 / All) at the
+	// ";;" boundary, preserving prior output for comment-free spans.
+	const children = [];
+	let lastEndIndex = node.startIndex;
+	let emittedSemi = false;
+	for (let i = 0; i < node.childCount; i++) {
+		const c = node.child(i);
+		for (const t of triviaLeaves(lastEndIndex, c.startIndex, ctx)) children.push(t);
+		if (!emittedSemi && !c.isNamed && ctx.source.slice(c.startIndex, c.endIndex) === ";;") {
+			if (lhsNode === null) children.push(implicitBound("Integer", "1"));
+			children.push({ type: "LeafNode", kind: "Token`SemiSemi", value: ";;", source: nodeSource(c, ctx.lineIndex) });
+			if (rhsNode === null) children.push(implicitBound("Symbol", "All"));
+			emittedSemi = true;
+		} else if (c.type === "comment") {
+			children.push(leaf(c, ctx));
+		} else if (c.isNamed) {
+			children.push(adaptNode(c, ctx));
 		}
+		lastEndIndex = c.endIndex;
 	}
-	// else named.length === 0: bare ;;
-
-	const lhs = lhsNode
-		? adaptNode(lhsNode, ctx)
-		: { type: "LeafNode", kind: "Integer", value: "1", source: nodeSource(semiSemiToken, ctx.lineIndex) };
-	const rhs = rhsNode
-		? adaptNode(rhsNode, ctx)
-		: { type: "LeafNode", kind: "Symbol", value: "All", source: nodeSource(semiSemiToken, ctx.lineIndex) };
+
 	return {
 		type: "BinaryNode",
 		op: "Span",
-		children: [lhs, semiSemiLeaf, rhs],
+		children,
 		source: nodeSource(node, ctx.lineIndex),
 	};
 }

package/src/translator/docComments.js

@@ -15,13 +15,55 @@ export function joinDocsWithSpace(docs) {
 	return joined;
 }
 
+export function isDocumentationCommentMarkerText(text) {
+	return /^\(\*\s*</u.test(String(text ?? ""));
+}
+
+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" &&
+		isDocumentationCommentMarkerText(node.value)
+	);
+}
+
+function hasMarkedDocumentationCommentEntry(entry, options) {
+	return (entry?.trailingComments ?? []).some((comment) =>
+		hasDocumentationCommentMarker(comment, options),
+	);
+}
+
+function normalizeDocumentationCommentMarker(text) {
+	return String(text).replace(/^\(\*\s*<\s*/u, "(* < ");
+}
+
+function normalizedCommentDoc(comment, options) {
+	const rendered = renderFlatDoc(comment.doc, options);
+	if (
+		!documentationCommentMarkersEnabled(options) ||
+		!isDocumentationCommentMarkerText(rendered) ||
+		rendered.includes("\n")
+	) {
+		return comment.doc;
+	}
+	return normalizeDocumentationCommentMarker(rendered);
+}
+
 export function joinCommentDocs(comments, options) {
 	const nonEmptyComments = comments.filter(
 		(comment) => comment?.doc !== "" && comment?.doc != null,
 	);
 	if (nonEmptyComments.length === 0) return "";
 
-	const joined = [nonEmptyComments[0].doc];
+	const joined = [normalizedCommentDoc(nonEmptyComments[0], options)];
 	for (let i = 1; i < nonEmptyComments.length; i++) {
 		joined.push(
 			sameLineCommentSeparator(
@@ -29,7 +71,7 @@ export function joinCommentDocs(comments, options) {
 				nonEmptyComments[i].node,
 				options,
 			),
-			nonEmptyComments[i].doc,
+			normalizedCommentDoc(nonEmptyComments[i], options),
 		);
 	}
 	return joined;
@@ -53,6 +95,13 @@ export function documentationCommentColumn(
 	options = normalizeWolframOptions(options);
 	const manual = options.wolframDocumentationCommentColumn ?? 0;
 	if (manual > 0) return manual;
+	if (
+		entries.some((entry) =>
+			hasMarkedDocumentationCommentEntry(entry, options),
+		)
+	) {
+		return options.printWidth ?? 80;
+	}
 	const padding = Math.max(
 		1,
 		options.wolframDocumentationCommentPadding ?? 2,

package/src/translator/nodes/call.js

@@ -117,28 +117,27 @@ function partGroupEntry(node) {
 }
 
 function groupPathEntries(groupNode, groupPath) {
-	const contents = groupNode.children.filter(
-		(child) => !isTrivia(child) && !isBracketToken(child),
+	// Flatten the comma-separated wrapper wherever it sits so its elements become
+	// individual entries even when a sibling comment keeps it from being the sole
+	// content of the group (mirrors rawArgEntries).
+	const wrapperIdx = groupNode.children.findIndex(
+		(child) => child.type === "InfixNode" && child.op === "Comma",
 	);
 
-	if (
-		contents.length === 1 &&
-		contents[0].type === "InfixNode" &&
-		contents[0].op === "Comma"
-	) {
-		const wrapperIdx = groupNode.children.indexOf(contents[0]);
-		return contents[0].children.reduce((entries, child, idx) => {
-			if (isTrivia(child)) return entries;
-			entries.push({
-				node: child,
-				path: [...groupPath, "children", wrapperIdx, "children", idx],
+	return groupNode.children.reduce((entries, child, idx) => {
+		if (isTrivia(child) || isBracketToken(child)) return entries;
+
+		if (idx === wrapperIdx) {
+			child.children.forEach((wrappedChild, wrappedIdx) => {
+				if (isTrivia(wrappedChild)) return;
+				entries.push({
+					node: wrappedChild,
+					path: [...groupPath, "children", idx, "children", wrappedIdx],
+				});
 			});
 			return entries;
-		}, []);
-	}
+		}
 
-	return groupNode.children.reduce((entries, child, idx) => {
-		if (isTrivia(child) || isBracketToken(child)) return entries;
 		entries.push({
 			node: child,
 			path: [...groupPath, "children", idx],

package/src/translator/nodes/group.js

@@ -64,29 +64,29 @@ function commentBoundary(leftEntry, rightEntry, options, fallback = line) {
 }
 
 function sequenceEntries(path, print, node) {
-	const contents = node.children.filter(
-		(child) => !isTrivia(child) && !isBracketToken(child),
+	// The comma-separated contents are wrapped in a single InfixNode[Comma].
+	// Flatten that wrapper wherever it sits so its rules become individual
+	// entries even when siblings (e.g. comments) keep it from being the sole
+	// content of the group.
+	const wrapperIdx = node.children.findIndex(
+		(child) => child.type === "InfixNode" && child.op === "Comma",
 	);
 
-	if (
-		contents.length === 1 &&
-		contents[0].type === "InfixNode" &&
-		contents[0].op === "Comma"
-	) {
-		const wrapperIdx = node.children.indexOf(contents[0]);
-		return contents[0].children.reduce((entries, child, idx) => {
-			if (isTrivia(child)) return entries;
-			entries.push({
-				node: child,
-				doc: path.call(print, "children", wrapperIdx, "children", idx),
-				path: ["children", wrapperIdx, "children", idx],
+	return node.children.reduce((entries, child, idx) => {
+		if (isTrivia(child) || isBracketToken(child)) return entries;
+
+		if (idx === wrapperIdx) {
+			child.children.forEach((wrappedChild, wrappedIdx) => {
+				if (isTrivia(wrappedChild)) return;
+				entries.push({
+					node: wrappedChild,
+					doc: path.call(print, "children", idx, "children", wrappedIdx),
+					path: ["children", idx, "children", wrappedIdx],
+				});
 			});
 			return entries;
-		}, []);
-	}
+		}
 
-	return node.children.reduce((entries, child, idx) => {
-		if (isTrivia(child) || isBracketToken(child)) return entries;
 		entries.push({
 			node: child,
 			doc: path.call(print, "children", idx),

package/src/translator/nodes/infix.js

@@ -4,6 +4,7 @@ const { builders } = doc;
 import { isTrivia, isComment } from "./leaf.js";
 import {
 	documentationCommentColumn,
+	hasDocumentationCommentMarker,
 	joinCommentDocs,
 	withAlignedTrailingComment,
 } from "../docComments.js";
@@ -190,9 +191,15 @@ export function printInfix(node, options, print) {
 		const trailingEntries = entries.filter(
 			(entry) => entry.trailingCommentDoc,
 		);
+		const hasMarkedDocumentationComment = trailingEntries.some((entry) =>
+			entry.trailingComments.some((comment) =>
+				hasDocumentationCommentMarker(comment, options),
+			),
+		);
 		const alignTrailingComments =
 			(options.wolframDocumentationCommentColumn ?? 0) > 0 ||
-			trailingEntries.length > 1;
+			trailingEntries.length > 1 ||
+			hasMarkedDocumentationComment;
 		const trailingColumn =
 			alignTrailingComments && trailingEntries.length > 0
 				? documentationCommentColumn(