Skip to content

Commit 25e69c8

Browse files
gitdog01gitdog01
committed
add JSDoc
1 parent 64a2ac9 commit 25e69c8

File tree

4 files changed

+191
-2
lines changed

4 files changed

+191
-2
lines changed

‎go.wasm‎

-13.9 KB
Binary file not shown.

‎go_src/main.go‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,33 @@
1+
//go:build js && wasm
2+
3+
// Package main implements a WebAssembly module that provides Go code formatting
4+
// functionality for the Prettier plugin. This package exposes the formatGo function
5+
// to JavaScript, enabling web-based Go code formatting using Go's built-in format package.
6+
//
7+
// The module is designed to be compiled to WebAssembly and loaded in Node.js
8+
// environments as part of the go-prettier-format plugin.
19
package main
210

311
import (
412
"go/format"
513
"syscall/js"
614
)
715

8-
// formatGo wraps go/format.Source to be callable from JavaScript.
9-
// It accepts Go source code as a string and returns the formatted code.
16+
// formatGo is a JavaScript-callable function that formats Go source code.
17+
// It wraps the standard library's go/format.Source function to be accessible
18+
// from JavaScript environments through WebAssembly.
19+
//
20+
// Parameters:
21+
// - this: The JavaScript 'this' context (unused)
22+
// - i: JavaScript arguments array where i[0] should contain the Go source code as a string
23+
//
24+
// Returns:
25+
// - js.Value: The formatted Go source code as a JavaScript string value
26+
// - If formatting fails due to syntax errors, returns the original code unchanged
27+
// - If no arguments are provided, returns js.Null() and logs an error
28+
//
29+
// The function handles syntax errors gracefully by returning the original code
30+
// and logging error details to the JavaScript console for debugging purposes.
1031
func formatGo(this js.Value, i []js.Value) interface{} {
1132
if len(i) == 0 {
1233
js.Global().Get("console").Call("error", "formatGo: missing code argument")
@@ -24,6 +45,14 @@ func formatGo(this js.Value, i []js.Value) interface{} {
2445
return js.ValueOf(string(formatted))
2546
}
2647

48+
// main initializes the WebAssembly module and exposes the formatGo function
49+
// to the JavaScript global scope. The function sets up a blocking channel
50+
// to prevent the WASM module from exiting, allowing it to serve as a
51+
// long-running service for formatting operations.
52+
//
53+
// The exposed formatGo function can be called from JavaScript as:
54+
//
55+
// global.formatGo(sourceCode)
2756
func main() {
2857
// Create a channel to keep the Go program running.
2958
// This is necessary because the WASM module would exit otherwise.

‎src/index.cjs‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,28 @@
1+
/**
2+
* @fileoverview Go Prettier Format Plugin (CommonJS)
3+
* A Prettier plugin for formatting Go code using WebAssembly.
4+
* This plugin leverages Go's native formatting capabilities through WASM.
5+
* This is the CommonJS version for compatibility with older Node.js environments.
6+
*/
7+
18
"use strict";
29

310
const fs = require("fs");
411
const path = require("path");
512

13+
/** @type {Promise<void>|null} */
614
let initializePromise;
715

16+
/**
17+
* Initializes the Go WebAssembly module for formatting Go code.
18+
* This function sets up the WASM runtime and makes the formatGo function
19+
* available on the global object.
20+
*
21+
* @async
22+
* @function initialize
23+
* @returns {Promise<void>} A promise that resolves when the WASM module is ready
24+
* @throws {Error} If the WASM file cannot be loaded or instantiated
25+
*/
826
function initialize() {
927
if (initializePromise) {
1028
return initializePromise;
@@ -36,6 +54,16 @@ function initialize() {
3654
return initializePromise;
3755
}
3856

57+
/**
58+
* Prettier language configuration for Go.
59+
* Defines the language settings, file extensions, and parser mappings.
60+
*
61+
* @type {Array<Object>}
62+
* @property {string} name - The display name of the language
63+
* @property {string[]} parsers - Array of parser names for this language
64+
* @property {string[]} extensions - File extensions associated with this language
65+
* @property {string[]} vscodeLanguageIds - VSCode language identifier mappings
66+
*/
3967
const languages = [
4068
{
4169
name: "Go",
@@ -45,18 +73,67 @@ const languages = [
4573
},
4674
];
4775

76+
/**
77+
* Prettier parser configuration for Go.
78+
* Defines how Go source code should be parsed and processed.
79+
*
80+
* @type {Object<string, Object>}
81+
* @property {Object} go - Go language parser configuration
82+
* @property {Function} go.parse - Parser function that returns the input text as-is
83+
* @property {string} go.astFormat - AST format identifier for the printer
84+
* @property {Function} go.locStart - Function to get the start location of a node
85+
* @property {Function} go.locEnd - Function to get the end location of a node
86+
*/
4887
const parsers = {
4988
go: {
89+
/**
90+
* Parse Go source code. For this plugin, we pass through the text as-is
91+
* since the actual formatting is handled by the Go WASM module.
92+
*
93+
* @param {string} text - The Go source code to parse
94+
* @returns {string} The input text unchanged
95+
*/
5096
parse: (text) => text,
5197
astFormat: "go-format",
5298
// These are required for Prettier to work
99+
/**
100+
* Get the start location of a node in the source code.
101+
*
102+
* @param {string} node - The node (in this case, the source text)
103+
* @returns {number} Always returns 0 as we treat the entire text as one node
104+
*/
53105
locStart: (node) => 0,
106+
/**
107+
* Get the end location of a node in the source code.
108+
*
109+
* @param {string} node - The node (in this case, the source text)
110+
* @returns {number} The length of the text
111+
*/
54112
locEnd: (node) => node.length,
55113
},
56114
};
57115

116+
/**
117+
* Prettier printer configuration for Go.
118+
* Defines how the parsed Go AST should be formatted back to text.
119+
*
120+
* @type {Object<string, Object>}
121+
* @property {Object} go-format - Go formatting printer configuration
122+
* @property {Function} go-format.print - Async function that formats Go code
123+
*/
58124
const printers = {
59125
"go-format": {
126+
/**
127+
* Format Go source code using the WebAssembly Go formatter.
128+
* This function initializes the WASM module if needed and calls the
129+
* global formatGo function exposed by the Go program.
130+
*
131+
* @async
132+
* @param {Object} path - Prettier's path object containing the source code
133+
* @param {Function} path.getValue - Function to get the current node value
134+
* @returns {Promise<string>} The formatted Go source code
135+
* @throws {Error} If the WASM module fails to initialize or format the code
136+
*/
60137
print: async (path) => {
61138
// The WASM module must be initialized before we can format.
62139
await initialize();
@@ -67,6 +144,13 @@ const printers = {
67144
},
68145
};
69146

147+
/**
148+
* @module go-prettier-format
149+
* @description Prettier plugin for formatting Go source code using WebAssembly
150+
* @exports {Object} languages - Language configuration for Prettier
151+
* @exports {Object} parsers - Parser configuration for Go language
152+
* @exports {Object} printers - Printer configuration for Go formatting
153+
*/
70154
module.exports = {
71155
languages,
72156
parsers,

‎src/index.js‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/**
2+
* @fileoverview Go Prettier Format Plugin
3+
* A Prettier plugin for formatting Go code using WebAssembly.
4+
* This plugin leverages Go's native formatting capabilities through WASM.
5+
*/
6+
17
"use strict";
28

39
import fs from "fs";
@@ -11,8 +17,19 @@ import "./wasm_exec.js";
1117
const __filename = fileURLToPath(import.meta.url);
1218
const __dirname = path.dirname(__filename);
1319

20+
/** @type {Promise<void>|null} */
1421
let initializePromise;
1522

23+
/**
24+
* Initializes the Go WebAssembly module for formatting Go code.
25+
* This function sets up the WASM runtime and makes the formatGo function
26+
* available on the global object.
27+
*
28+
* @async
29+
* @function initialize
30+
* @returns {Promise<void>} A promise that resolves when the WASM module is ready
31+
* @throws {Error} If the WASM file cannot be loaded or instantiated
32+
*/
1633
function initialize() {
1734
if (initializePromise) {
1835
return initializePromise;
@@ -40,6 +57,16 @@ function initialize() {
4057
return initializePromise;
4158
}
4259

60+
/**
61+
* Prettier language configuration for Go.
62+
* Defines the language settings, file extensions, and parser mappings.
63+
*
64+
* @type {Array<Object>}
65+
* @property {string} name - The display name of the language
66+
* @property {string[]} parsers - Array of parser names for this language
67+
* @property {string[]} extensions - File extensions associated with this language
68+
* @property {string[]} vscodeLanguageIds - VSCode language identifier mappings
69+
*/
4370
const languages = [
4471
{
4572
name: "Go",
@@ -49,18 +76,67 @@ const languages = [
4976
},
5077
];
5178

79+
/**
80+
* Prettier parser configuration for Go.
81+
* Defines how Go source code should be parsed and processed.
82+
*
83+
* @type {Object<string, Object>}
84+
* @property {Object} go - Go language parser configuration
85+
* @property {Function} go.parse - Parser function that returns the input text as-is
86+
* @property {string} go.astFormat - AST format identifier for the printer
87+
* @property {Function} go.locStart - Function to get the start location of a node
88+
* @property {Function} go.locEnd - Function to get the end location of a node
89+
*/
5290
const parsers = {
5391
go: {
92+
/**
93+
* Parse Go source code. For this plugin, we pass through the text as-is
94+
* since the actual formatting is handled by the Go WASM module.
95+
*
96+
* @param {string} text - The Go source code to parse
97+
* @returns {string} The input text unchanged
98+
*/
5499
parse: (text) => text,
55100
astFormat: "go-format",
56101
// These are required for Prettier to work
102+
/**
103+
* Get the start location of a node in the source code.
104+
*
105+
* @param {string} node - The node (in this case, the source text)
106+
* @returns {number} Always returns 0 as we treat the entire text as one node
107+
*/
57108
locStart: (node) => 0,
109+
/**
110+
* Get the end location of a node in the source code.
111+
*
112+
* @param {string} node - The node (in this case, the source text)
113+
* @returns {number} The length of the text
114+
*/
58115
locEnd: (node) => node.length,
59116
},
60117
};
61118

119+
/**
120+
* Prettier printer configuration for Go.
121+
* Defines how the parsed Go AST should be formatted back to text.
122+
*
123+
* @type {Object<string, Object>}
124+
* @property {Object} go-format - Go formatting printer configuration
125+
* @property {Function} go-format.print - Async function that formats Go code
126+
*/
62127
const printers = {
63128
"go-format": {
129+
/**
130+
* Format Go source code using the WebAssembly Go formatter.
131+
* This function initializes the WASM module if needed and calls the
132+
* global formatGo function exposed by the Go program.
133+
*
134+
* @async
135+
* @param {Object} path - Prettier's path object containing the source code
136+
* @param {Function} path.getValue - Function to get the current node value
137+
* @returns {Promise<string>} The formatted Go source code
138+
* @throws {Error} If the WASM module fails to initialize or format the code
139+
*/
64140
print: async (path) => {
65141
// The WASM module must be initialized before we can format.
66142
await initialize();

0 commit comments

Comments
 (0)