Skip to content

Commit 5eb10d4

Browse files
dcodeIOdcodeIO
committed
Document the purpose of most files
1 parent d45eb93 commit 5eb10d4

30 files changed

+193
-83
lines changed

‎dist/asc.js‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/asc.js.map‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/assemblyscript.js‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/assemblyscript.js.map‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/ast.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file Abstract syntax tree representing a source file once parsed.
3+
*/
4+
15
import {
26
CommonFlags,
37
PATH_DELIMITER,

‎src/builtins.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file Built-in elements providing otherwise hard-to-implement functionality.
3+
*/
4+
15
import {
26
Compiler,
37
ConversionKind,

‎src/compiler.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file The AssemblyScript compiler.
3+
*/
4+
15
import {
26
compileCall as compileBuiltinCall,
37
compileGetConstant as compileBuiltinGetConstant,

‎src/decompiler.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file A decompiler that generates low-level AssemblyScript from WebAssembly binaries.
3+
*/
4+
15
import {
26
Module,
37
NativeType,

‎src/diagnostics.ts‎

Lines changed: 66 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file Shared diagnostic handling inherited by the parser and the compiler.
3+
*/
4+
15
import {
26
Range
37
} from "./ast";
@@ -16,48 +20,71 @@ export {
1620
diagnosticCodeToString
1721
} from "./diagnosticMessages.generated";
1822

23+
/** Indicates the category of a {@link DiagnosticMessage}. */
1924
export enum DiagnosticCategory {
25+
/** Informatory message. */
2026
INFO,
27+
/** Warning message. */
2128
WARNING,
29+
/** Error message. */
2230
ERROR
2331
}
2432

33+
/** Returns the string representation of the specified diagnostic category. */
2534
export function diagnosticCategoryToString(category: DiagnosticCategory): string {
2635
switch (category) {
2736
case DiagnosticCategory.INFO: return "INFO";
2837
case DiagnosticCategory.WARNING: return "WARNING";
2938
case DiagnosticCategory.ERROR: return "ERROR";
30-
default: return "";
39+
default: {
40+
assert(false);
41+
return "";
42+
}
3143
}
3244
}
3345

34-
const colorBlue: string = "\u001b[93m";
35-
const colorYellow: string = "\u001b[93m";
36-
const colorRed: string = "\u001b[91m";
37-
const colorReset: string = "\u001b[0m";
46+
/** ANSI escape sequence for blue foreground. */
47+
export const COLOR_BLUE: string = "\u001b[93m";
48+
/** ANSI escape sequence for yellow foreground. */
49+
export const COLOR_YELLOW: string = "\u001b[93m";
50+
/** ANSI escape sequence for red foreground. */
51+
export const COLOR_RED: string = "\u001b[91m";
52+
/** ANSI escape sequence to reset the foreground color. */
53+
export const COLOR_RESET: string = "\u001b[0m";
3854

55+
/** Returns the ANSI escape sequence for the specified category. */
3956
export function diagnosticCategoryToColor(category: DiagnosticCategory): string {
4057
switch (category) {
41-
case DiagnosticCategory.INFO: return colorBlue;
42-
case DiagnosticCategory.WARNING: return colorYellow;
43-
case DiagnosticCategory.ERROR: return colorRed;
44-
default: return "";
58+
case DiagnosticCategory.INFO: return COLOR_BLUE;
59+
case DiagnosticCategory.WARNING: return COLOR_YELLOW;
60+
case DiagnosticCategory.ERROR: return COLOR_RED;
61+
default: {
62+
assert(false);
63+
return "";
64+
}
4565
}
4666
}
4767

68+
/** Represents a diagnostic message. */
4869
export class DiagnosticMessage {
4970

71+
/** Message code. */
5072
code: i32;
73+
/** Message category. */
5174
category: DiagnosticCategory;
75+
/** Message text. */
5276
message: string;
77+
/** Respective source range, if any. */
5378
range: Range | null = null;
5479

55-
constructor(code: i32, category: DiagnosticCategory, message: string) {
80+
/** Constructs a new diagnostic message. */
81+
private constructor(code: i32, category: DiagnosticCategory, message: string) {
5682
this.code = code;
5783
this.category = category;
5884
this.message = message;
5985
}
6086

87+
/** Creates a new diagnostic message of the specified category. */
6188
static create(
6289
code: DiagnosticCode,
6390
category: DiagnosticCategory,
@@ -72,6 +99,7 @@ export class DiagnosticMessage {
7299
return new DiagnosticMessage(code, category, message);
73100
}
74101

102+
/** Creates a new informatory diagnostic message. */
75103
static createInfo(
76104
code: DiagnosticCode,
77105
arg0: string | null = null,
@@ -80,6 +108,7 @@ export class DiagnosticMessage {
80108
return DiagnosticMessage.create(code, DiagnosticCategory.INFO, arg0, arg1);
81109
}
82110

111+
/** Creates a new warning diagnostic message. */
83112
static createWarning(
84113
code: DiagnosticCode,
85114
arg0: string | null = null,
@@ -88,6 +117,7 @@ export class DiagnosticMessage {
88117
return DiagnosticMessage.create(code, DiagnosticCategory.WARNING, arg0, arg1);
89118
}
90119

120+
/** Creates a new error diagnostic message. */
91121
static createError(
92122
code: DiagnosticCode,
93123
arg0: string | null = null,
@@ -96,11 +126,13 @@ export class DiagnosticMessage {
96126
return DiagnosticMessage.create(code, DiagnosticCategory.ERROR, arg0, arg1);
97127
}
98128

129+
/** Adds a source range to this message. */
99130
withRange(range: Range): this {
100131
this.range = range;
101132
return this;
102133
}
103134

135+
/** Converts this message to a string. */
104136
toString(): string {
105137
if (this.range) {
106138
return (
@@ -127,34 +159,33 @@ export class DiagnosticMessage {
127159
}
128160
}
129161

162+
/** Formats a diagnostic message, optionally with terminal colors and source context. */
130163
export function formatDiagnosticMessage(
131164
message: DiagnosticMessage,
132165
useColors: bool = false,
133166
showContext: bool = false
134167
): string {
135-
// format context first (uses same string builder)
136-
var context = "";
137-
if (message.range && showContext) {
138-
context = formatDiagnosticContext(message.range, useColors);
139-
}
140168

141169
// general information
142170
var sb: string[] = [];
143171
if (useColors) sb.push(diagnosticCategoryToColor(message.category));
144172
sb.push(diagnosticCategoryToString(message.category));
145-
if (useColors) sb.push(colorReset);
173+
if (useColors) sb.push(COLOR_RESET);
146174
sb.push(message.code < 1000 ? " AS" : " TS");
147175
sb.push(message.code.toString(10));
148176
sb.push(": ");
149177
sb.push(message.message);
150178

151-
// range information if available
179+
// include range information if available
152180
if (message.range) {
181+
182+
// include context information if requested
153183
let range = message.range;
154184
if (showContext) {
155185
sb.push("\n");
156-
sb.push(context);
186+
sb.push(formatDiagnosticContext(message.range, useColors));
157187
}
188+
158189
sb.push("\n");
159190
sb.push(" in ");
160191
sb.push(range.source.normalizedPath);
@@ -167,6 +198,7 @@ export function formatDiagnosticMessage(
167198
return sb.join("");
168199
}
169200

201+
/** Formats the diagnostic context for the specified range, optionally with terminal colors. */
170202
export function formatDiagnosticContext(range: Range, useColors: bool = false): string {
171203
var text = range.source.text;
172204
var len = text.length;
@@ -187,26 +219,30 @@ export function formatDiagnosticContext(range: Range, useColors: bool = false):
187219
sb.push(" ");
188220
start++;
189221
}
190-
if (useColors) sb.push(colorRed);
222+
if (useColors) sb.push(COLOR_RED);
191223
if (range.start == range.end) {
192224
sb.push("^");
193225
} else {
194226
while (start++ < range.end) {
195227
sb.push("~");
196228
}
197229
}
198-
if (useColors) sb.push(colorReset);
230+
if (useColors) sb.push(COLOR_RESET);
199231
return sb.join("");
200232
}
201233

234+
/** Base class of all diagnostic emitters. */
202235
export abstract class DiagnosticEmitter {
203236

237+
/** Diagnostic messages emitted so far. */
204238
diagnostics: DiagnosticMessage[];
205239

206-
constructor(diagnostics: DiagnosticMessage[] | null = null) {
240+
/** Initializes this diagnostic emitter. */
241+
protected constructor(diagnostics: DiagnosticMessage[] | null = null) {
207242
this.diagnostics = diagnostics ? <DiagnosticMessage[]>diagnostics : new Array();
208243
}
209244

245+
/** Emits a diagnostic message of the specified category. */
210246
emitDiagnostic(
211247
code: DiagnosticCode,
212248
category: DiagnosticCategory,
@@ -221,33 +257,36 @@ export abstract class DiagnosticEmitter {
221257
// console.log(<string>new Error("stack").stack);
222258
}
223259

224-
error(
260+
/** Emits an informatory diagnostic message. */
261+
info(
225262
code: DiagnosticCode,
226263
range: Range,
227264
arg0: string | null = null,
228265
arg1: string | null = null,
229266
arg2: string | null = null
230267
): void {
231-
this.emitDiagnostic(code, DiagnosticCategory.ERROR, range, arg0, arg1, arg2);
268+
this.emitDiagnostic(code, DiagnosticCategory.INFO, range, arg0, arg1, arg2);
232269
}
233270

234-
info(
271+
/** Emits a warning diagnostic message. */
272+
warning(
235273
code: DiagnosticCode,
236274
range: Range,
237275
arg0: string | null = null,
238276
arg1: string | null = null,
239277
arg2: string | null = null
240278
): void {
241-
this.emitDiagnostic(code, DiagnosticCategory.INFO, range, arg0, arg1, arg2);
279+
this.emitDiagnostic(code, DiagnosticCategory.WARNING, range, arg0, arg1, arg2);
242280
}
243281

244-
warning(
282+
/** Emits an error diagnostic message. */
283+
error(
245284
code: DiagnosticCode,
246285
range: Range,
247286
arg0: string | null = null,
248287
arg1: string | null = null,
249288
arg2: string | null = null
250289
): void {
251-
this.emitDiagnostic(code, DiagnosticCategory.WARNING, range, arg0, arg1, arg2);
290+
this.emitDiagnostic(code, DiagnosticCategory.ERROR, range, arg0, arg1, arg2);
252291
}
253292
}

‎src/glue/binaryen-c.d.ts‎

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,7 @@
1-
/*
2-
3-
Binaryen's C-API.
4-
5-
The WebAssembly version of the compiler will be linked against Binaryen
6-
compiled to WebAssembly with these functions present in the binary while the
7-
JS version calls them on the global object.
8-
9-
see: https://github.com/WebAssembly/binaryen/blob/master/src/binaryen-c.h
10-
11-
*/
1+
/**
2+
* @file TypeScript definitions for Binaryen's C-API.
3+
* @see https://github.com/WebAssembly/binaryen/blob/master/src/binaryen-c.h
4+
*/
125

136
declare function _malloc(size: usize): usize;
147
declare function _free(ptr: usize): void;

0 commit comments

Comments
 (0)