feat(wasm-api): add doc string word wrapping

- update prefixLines(), add target line width arg - update ICodeGen & CodeGenOpts - update all codegens - update deps
thi-ng · Oct 2, 2022 · c0b8e15 · c0b8e15
1 parent 337b2a2
commit c0b8e15
Show file tree

Hide file tree

Showing 8 changed files with 47 additions and 26 deletions.
diff --git a/packages/wasm-api/package.json b/packages/wasm-api/package.json
@@ -47,7 +47,8 @@
 		"@thi.ng/hex": "^2.2.0",
 		"@thi.ng/idgen": "^2.1.13",
 		"@thi.ng/logger": "^1.3.0",
-		"@thi.ng/paths": "^5.1.15"
+		"@thi.ng/paths": "^5.1.15",
+		"@thi.ng/strings": "^3.3.12"
 	},
 	"devDependencies": {
 		"@microsoft/api-extractor": "^7.31.1",

diff --git a/packages/wasm-api/src/api.ts b/packages/wasm-api/src/api.ts
@@ -390,6 +390,12 @@ export interface CodeGenOpts extends CodeGenOptsBase {
 	 * @defaultValue false
 	 */
 	debug: boolean;
+	/**
+	 * Target line width for word wrapping doc strings
+	 *
+	 * @defaultValue 80
+	 */
+	lineWidth: number;
 }
 
 export interface ICodeGen {
@@ -404,7 +410,12 @@ export interface ICodeGen {
 	/**
 	 * Docstring codegen
 	 */
-	doc: (doc: string, acc: string[], topLevel?: boolean) => void;
+	doc: (
+		doc: string,
+		acc: string[],
+		opts: CodeGenOpts,
+		topLevel?: boolean
+	) => void;
 	/**
 	 * Codegen for enum types.
 	 */

diff --git a/packages/wasm-api/src/codegen.ts b/packages/wasm-api/src/codegen.ts
@@ -177,6 +177,7 @@ export const generateTypes = (
 		header: true,
 		stringType: "slice",
 		uppercaseEnums: true,
+		lineWidth: 80,
 		...opts,
 	};
 	prepareTypes(types, $opts);
@@ -185,6 +186,7 @@ export const generateTypes = (
 		codegen.doc(
 			`Generated by ${PKG_NAME} at ${new Date().toISOString()} - DO NOT EDIT!`,
 			res,
+			$opts,
 			true
 		);
 		res.push("");
@@ -196,7 +198,7 @@ export const generateTypes = (
 	$opts.pre && res.push($opts.pre, "");
 	for (let id in types) {
 		const type = types[id];
-		type.doc && codegen.doc(type.doc, res);
+		type.doc && codegen.doc(type.doc, res, $opts);
 		codegen[type.type](<any>type, types, res, $opts);
 	}
 	$opts.post && res.push("", $opts.post);

diff --git a/packages/wasm-api/src/codegen/c11.ts b/packages/wasm-api/src/codegen/c11.ts
@@ -58,8 +58,8 @@ ${opts.debug ? "\n#include <stdalign.h>" : ""}
 
 		post: () => opts.post || "",
 
-		doc: (doc, acc) => {
-			acc.push(prefixLines("// ", doc));
+		doc: (doc, acc, opts) => {
+			acc.push(...prefixLines("// ", doc, opts.lineWidth));
 		},
 
 		enum: (e, _, acc, opts) => {
@@ -74,7 +74,7 @@ ${opts.debug ? "\n#include <stdalign.h>" : ""}
 			for (let v of e.values) {
 				let line: string;
 				if (!isString(v)) {
-					v.doc && gen.doc(v.doc, lines);
+					v.doc && gen.doc(v.doc, lines, opts);
 					line = enumName(opts, v.name);
 					if (v.value != null) line += ` = ${v.value}`;
 				} else {
@@ -98,7 +98,7 @@ ${opts.debug ? "\n#include <stdalign.h>" : ""}
 					res.push(`uint8_t __pad${padID++}[${f.pad}];`);
 					continue;
 				}
-				f.doc && gen.doc(f.doc, res);
+				f.doc && gen.doc(f.doc, res, opts);
 				const fconst = f.const ? "const " : "";
 				let ftype =
 					f.type === "string"

diff --git a/packages/wasm-api/src/codegen/typescript.ts b/packages/wasm-api/src/codegen/typescript.ts
@@ -74,12 +74,8 @@ import { Pointer, ${__stringImpl(
 
 		post: () => opts.post || "",
 
-		doc: (doc, acc) => {
-			if (doc.indexOf("\n") !== -1) {
-				acc.push("/**", prefixLines(indent + " * ", doc), " */");
-			} else {
-				acc.push(`/** ${doc} */`);
-			}
+		doc: (doc, acc, opts) => {
+			acc.push("/**", ...prefixLines(" * ", doc, opts.lineWidth), " */");
 		},
 
 		enum: (e, _, acc, opts) => {
@@ -88,7 +84,7 @@ import { Pointer, ${__stringImpl(
 			for (let v of e.values) {
 				let line: string;
 				if (!isString(v)) {
-					v.doc && gen.doc(v.doc, res);
+					v.doc && gen.doc(v.doc, res, opts);
 					line = enumName(opts, v.name);
 					if (v.value != null) line += ` = ${v.value}`;
 				} else {
@@ -110,7 +106,7 @@ import { Pointer, ${__stringImpl(
 			);
 			for (let f of struct.fields) {
 				if (isPadding(f)) continue;
-				f.doc && gen.doc(f.doc, lines);
+				f.doc && gen.doc(f.doc, lines, opts);
 				const ftype = __fieldType(f, opts);
 				fieldTypes[f.name] = ftype;
 				lines.push(`${f.name}: ${ftype};`);

diff --git a/packages/wasm-api/src/codegen/utils.ts b/packages/wasm-api/src/codegen/utils.ts
@@ -1,5 +1,6 @@
 import type { BigType } from "@thi.ng/api";
 import { isString } from "@thi.ng/checks/is-string";
+import { wordWrapLine, wordWrapLines } from "@thi.ng/strings/word-wrap";
 import type { CodeGenOpts, StructField, WasmPrim, WasmPrim32 } from "../api.js";
 
 /**
@@ -30,16 +31,23 @@ export const isWasmString = (x: string): x is "string" => x === "string";
 export const isPadding = (f: StructField) => f.pad != null && f.pad > 0;
 
 /**
- * Takes an array of strings or splits given string into lines, prefixes each
- * line with given `prefix` and then returns rejoined result.
+ * Takes an array of strings or splits given string into lines, word wraps and
+ * then prefixes each line with given `width` and `prefix`. Returns array of new
+ * lines.
  *
  * @param prefix
  * @param str
+ * @param width
  */
-export const prefixLines = (prefix: string, str: string | string[]) =>
-	(isString(str) ? str.split("\n") : str)
-		.map((line) => prefix + line)
-		.join("\n");
+export const prefixLines = (
+	prefix: string,
+	str: string | string[],
+	width: number
+) =>
+	(isString(str)
+		? wordWrapLines(str, { width })
+		: str.flatMap((x) => wordWrapLine(x, { width }))
+	).map((line) => prefix + line);
 
 /**
  * Returns true if `type` is "slice".

diff --git a/packages/wasm-api/src/codegen/zig.ts b/packages/wasm-api/src/codegen/zig.ts
@@ -32,8 +32,10 @@ export const ZIG = (opts: Partial<ZigOpts> = {}) => {
 
 		post: () => opts.post || "",
 
-		doc: (doc, acc, topLevel = false) => {
-			acc.push(prefixLines(topLevel ? "//! " : "/// ", doc));
+		doc: (doc, acc, opts, topLevel = false) => {
+			acc.push(
+				...prefixLines(topLevel ? "//! " : "/// ", doc, opts.lineWidth)
+			);
 		},
 
 		enum: (e, _, acc, opts) => {
@@ -42,7 +44,7 @@ export const ZIG = (opts: Partial<ZigOpts> = {}) => {
 			for (let v of e.values) {
 				let line: string;
 				if (!isString(v)) {
-					v.doc && gen.doc(v.doc, lines);
+					v.doc && gen.doc(v.doc, lines, opts);
 					line = enumName(opts, v.name);
 					if (v.value != null) line += ` = ${v.value}`;
 				} else {
@@ -70,7 +72,7 @@ export const ZIG = (opts: Partial<ZigOpts> = {}) => {
 					res.push(`__pad${padID++}: [${f.pad}]u8,`);
 					continue;
 				}
-				f.doc && gen.doc(f.doc, res);
+				f.doc && gen.doc(f.doc, res, opts);
 				let ftype =
 					f.type === "string"
 						? isStringSlice(opts.stringType)

diff --git a/yarn.lock b/yarn.lock
@@ -4848,7 +4848,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@thi.ng/wasm-api@workspace:packages/wasm-api":
+"@thi.ng/wasm-api@workspace:^, @thi.ng/wasm-api@workspace:packages/wasm-api":
   version: 0.0.0-use.local
   resolution: "@thi.ng/wasm-api@workspace:packages/wasm-api"
   dependencies:
@@ -4865,6 +4865,7 @@ __metadata:
     "@thi.ng/idgen": ^2.1.13
     "@thi.ng/logger": ^1.3.0
     "@thi.ng/paths": ^5.1.15
+    "@thi.ng/strings": ^3.3.12
     "@thi.ng/testament": ^0.3.0
     rimraf: ^3.0.2
     tools: "workspace:^"