added docs.

Kuinox · Kuinox · commit 335b1aabe66d · 2024-09-22T23:47:40.000+02:00
diff --git a/src/Draco.Editor.Web/app/build.js b/src/Draco.Editor.Web/app/build.js
@@ -20,6 +20,9 @@ const outDir = path.join(__dirname, distDir);
 const binFolder = process.argv[2];
 const debug = binFolder.includes('Debug');
 
+// rebundling the dotnet.js with vite bundler
+// this was needed because firefox didn't supported esmodule in webworker
+// it does now (the bugzilla ticket i followed on the subject was completed), so it may not be needed anymore.
 async function dotnetjsBuild() {
     await viteBuild(defineConfig({ // Yes, I'm using another bundler, because this one bundle correctly dotnet.js to CJS...
         build: {
diff --git a/src/Draco.Editor.Web/app/favicon-downloader.js b/src/Draco.Editor.Web/app/favicon-downloader.js
@@ -1,3 +1,6 @@
+// this simply take two svg, slap a css media query so a single image can be used for both light and dark theme
+// this is necessary for the favicon, to have dark/light favicon
+
 function stripXMLHeader(xml) {
     const indexOf = xml.indexOf('\n');
     return xml.slice(indexOf);
diff --git a/src/Draco.Editor.Web/app/index.html b/src/Draco.Editor.Web/app/index.html
@@ -11,7 +11,7 @@
 </head>
 
 <body>
-    <div id="layoutContainer">
+    <div id="layoutContainer"> <!-- for golden layout. -->
     </div>
     <script src="ts/app.js" type="module"></script>
 </body>
diff --git a/src/Draco.Editor.Web/app/ts/LayoutComponents/StdOut.ts b/src/Draco.Editor.Web/app/ts/LayoutComponents/StdOut.ts
@@ -3,6 +3,10 @@ import { Terminal } from 'xterm';
 import { FitAddon } from 'xterm-addon-fit';
 import { getDownloadViewElement } from '../cache.js';
 
+
+/**
+ * This simply setup a xterm (it's what vscode uses) terminal
+ */
 export class StdOut {
     static terminals: Terminal[] = [];
 
diff --git a/src/Draco.Editor.Web/app/ts/LayoutComponents/TextDisplay.ts b/src/Draco.Editor.Web/app/ts/LayoutComponents/TextDisplay.ts
@@ -3,6 +3,8 @@ import { ComponentContainer } from 'golden-layout';
 import { getDownloadViewElement } from '../cache.js';
 import { subscribeOutputChange } from '../dotnet.js';
 
+// this setup a readonly monaco editor to view code output (IR/IL)
+
 export class TextDisplay {
     static editors = {};
 
@@ -17,8 +19,8 @@ export class TextDisplay {
         div.classList.add('output-viewer');
         this.rootElement.appendChild(div);
         const editor = monaco.editor.create(div, {
-            theme: 'dynamic-theme',
-            language: container.title.toLowerCase(),
+            theme: 'dynamic-theme', // this is a theme with create that we update dynamically when the user change the theme
+            language: container.title.toLowerCase(), // we use the title of the container to set the language
             readOnly: true,
             scrollbar: {
                 vertical: 'visible'
@@ -38,6 +40,8 @@ export class TextDisplay {
             editor.layout();
         });
         subscribeOutputChange((arg) => {
+            // subscribeOutputChange fire when there is a new 'output',
+            // the title of our container correspond to the type of output it display.
             if (arg.outputType == container.title) {
                 editor.setValue(arg.value);
             }
diff --git a/src/Draco.Editor.Web/app/ts/LayoutComponents/TextInput.ts b/src/Draco.Editor.Web/app/ts/LayoutComponents/TextInput.ts
@@ -2,6 +2,7 @@ import * as monaco from 'monaco-editor/esm/vs/editor/editor.main.js';
 import { ComponentContainer } from 'golden-layout';
 import { inputCode } from '../app.js';
 
+// this setup a monaco editor to input the code.
 export class TextInput {
     static editors = [];
 
@@ -16,7 +17,7 @@ export class TextInput {
         const editor = monaco.editor.create(div, {
             value: inputCode,
             language: 'draco',
-            theme: 'dynamic-theme',
+            theme: 'dynamic-theme', // this is a theme with create that we update dynamically when the user change the theme
             scrollbar: {
                 vertical: 'visible'
             },
diff --git a/src/Draco.Editor.Web/app/ts/app.ts b/src/Draco.Editor.Web/app/ts/app.ts
@@ -8,6 +8,8 @@ import { TextInput } from './LayoutComponents/TextInput.js';
 import { loadThemes } from './loadThemes.js';
 import { Settings } from './LayoutComponents/Settings.js';
 
+// this file is the entry point.
+
 function updateHash(code: string) {
     // setting the URL Hash with the state of the editor.
     // Doing this before invoking DotNet will allow sharing hard crash.
@@ -18,8 +20,9 @@ function updateHash(code: string) {
     buffer.set(compressed, 1);
     history.replaceState(undefined, undefined, '#' + fromBase64ToBase64URL(toBase64(buffer)));
 }
-// This file is run on page load.
-// This run before blazor load, and will tell blazor to start.
+
+// that's because monaco doesn't help you when you have a bundler, you have to do it by hand.
+// https://github.com/microsoft/monaco-editor/blob/main/samples/browser-esm-esbuild/index.js
 
 self.MonacoEnvironment = {
     // Web Workers need to start a new script, by url.
@@ -29,7 +32,7 @@ self.MonacoEnvironment = {
     }
 };
 
-const hash = window.location.hash.slice(1);
+const hash = window.location.hash.slice(1); // retrieve hash, which contain the stored code.
 export let inputCode = `import System.Console;
 
 func main() {
@@ -109,12 +112,13 @@ goldenLayout.registerComponentConstructor('Settings', Settings);
 
 goldenLayout.loadLayout(config);
 const inputEditor = TextInput.editors[0];
-inputEditor.getModel().onDidChangeContent(() => {
+inputEditor.getModel().onDidChangeContent(() => { // when the input editor content change...
     const code = inputEditor.getModel().getValue();
-    setCode(code);
-    updateHash(code);
+    setCode(code); // this sends the code to the dotnet worker.
+    updateHash(code); // and update the hash of the URL.
 });
-subscribeOutputChange((arg) => {
+
+subscribeOutputChange((arg) => { // and this piece of code that have nothing to do here, update the xterm terminal with what the dotnet worker sent.
     if (arg.outputType == 'stdout') {
         if (arg.clear) {
             StdOut.terminals[0].reset();
@@ -123,5 +127,5 @@ subscribeOutputChange((arg) => {
     }
 });
 
-loadThemes();
+loadThemes(); // this does the black magic in order to have vscode theme on monaco.
 initDotnetWorkers(inputCode);
diff --git a/src/Draco.Editor.Web/app/ts/cache.ts b/src/Draco.Editor.Web/app/ts/cache.ts
@@ -1,8 +1,13 @@
 import { blobToBase64 } from './helpers.js';
 import { buildDate } from './metadata.js';
 
+// this is a dll cache to avoid downloading the same assembly multiple times.
+
 const elements = [];
 
+// when you download assemblies, we have a progress bar to show the download progress.
+// to be honest it also have a cool factor and i like it.
+// it also make people patient to have a progress bar :p.
 export function getDownloadViewElement() {
     const downloadViewElement = document.createElement('div');
     downloadViewElement.classList.add('monaco-editor');
@@ -15,6 +20,10 @@ export function getDownloadViewElement() {
     return downloadViewElement;
 }
 
+// dotnet js would download every single assembly every single time,
+// it provided a way to have custom logic back thenn, but it simply didnt worked, and it was not documented at all.
+// a way i found by browsing the code, is that if you sets the buffer field, it wont download the dll and use the buffer as the dll.
+// so we take the dotnet js config, download/pull from cache all the dll listed in it, and set the buffer field.
 export async function downloadAssemblies(cfg: unknown) {
     await ensureCacheUpToDate();
     const assets = cfg['assets'];
@@ -91,10 +100,6 @@ async function downloadAssembly(dlPath: string, asset: unknown): Promise<void> {
     });
 }
 
-function wait(milliseconds) {
-    return new Promise(resolve => setTimeout(resolve, milliseconds));
-}
-
 async function progressFetch(url: string, onProgress: (loaded: number, total: number) => void): Promise<Blob> {
     const response = await fetch(url);
     const contentLength = response.headers.get('content-length');
diff --git a/src/Draco.Editor.Web/app/ts/dotnet.ts b/src/Draco.Editor.Web/app/ts/dotnet.ts
@@ -1,4 +1,5 @@
 import { downloadAssemblies } from './cache.js';
+// this file handle the communication with the .NET worker.
 
 const compilerWorker = new Worker('worker.js'); // first thing: we start the worker so it loads in parallel.
 let runtimeWorker: Worker | undefined;
@@ -11,21 +12,30 @@ compilerWorker.onmessage = async (ev) => {
         message: string;
     };
     switch (msg.type) {
-    case 'setOutputText': {
+    case 'setOutputText': { // the worker is sending us some output
         const parsed = JSON.parse(msg.message);
         onOutputChange(parsed['OutputType'], parsed['Text'], true);
         break;
     }
-    case 'runtimeAssembly': {
+    case 'runtimeAssembly': { // the worker sent a compiled dll to run.
         if (runtimeWorker != undefined) {
             runtimeWorker.terminate();
         }
         onOutputChange('stdout', 'Loading script\'s .NET Runtime...', true);
+
         runtimeWorker = new Worker('worker.js');
+
+        // our small dotnet wrapper around the compiler:
+        // listed all the assemblies that this dll will need
+        // and built a json that mono wasm understand to run a .NET dll.
+
+        // the small wrapepr part generate an ideal config file, this script here bring the reality back to it: dotnet js api is far from being usable.
         const cfg = JSON.parse(msg.message);
         console.log('Starting worker with boot config:');
-        cfg['disableInterop'] = true;
+
+        cfg['disableInterop'] = true; // we don't do js-dotnet interop in user dlls for now.
         const assets = cfg['assets'];
+        // for some reason, mono js really need these two files. why does it doesn't do itself ? good question.
         assets.unshift({
             name: jsModuleNativeName,
             behavior: 'js-module-native',
@@ -34,8 +44,8 @@ compilerWorker.onmessage = async (ev) => {
             name: jsModuleRuntimeName,
             behavior: 'js-module-runtime',
         });
-        await downloadAssemblies(cfg);
-        runtimeWorker.postMessage(cfg);
+        await downloadAssemblies(cfg); // this download the assemblies by ourself, i explain in the function why we do that.
+        runtimeWorker.postMessage(cfg); // we send the config to the worker.
         let shouldClean = true;
         runtimeWorker.onmessage = (e) => {
             const runtimeMsg = e.data as {
@@ -84,9 +94,14 @@ export function unsubscribeOutputChange(listener: (arg: { outputType: string; va
 }
 
 export async function initDotnetWorkers(initCode: string) {
+    // msbuild generated a shiny file for dotnet js, it's called blazor even if we don't use blazor
     const cfg = await (await fetch('_framework/blazor.boot.json')).json();
+    // dotnet js doesn't cache dlls, so we again use our download mechanism to cache them.
+    // also, there is multiple way to structure this config file, because why not.
+    // and the way msbuild generate this file, don't allow to use the buffer trick explained in cache.ts.
+    // so I recreate the config file, using this config structure that i understand.
     console.log(cfg);
-    const assets: unknown[] = Object.keys(cfg.resources.assembly).map(
+    const assets: unknown[] = Object.keys(cfg.resources.assembly).map( // this rewrite the msbuild generated config into the config structure i use.
         s => {
             return {
                 'behavior': 'assembly',
@@ -98,6 +113,11 @@ export async function initDotnetWorkers(initCode: string) {
         'behavior': 'dotnetwasm',
         'name': 'dotnet.native.wasm'
     });
+
+    // if i remember correctly, the file structure they use have dedicated fields to specify theses 2 files
+    // since we don't use their file strucutre, we have to add them manually.
+    // Luckily, we can just pull the value from the msbuild generated file.
+
     jsModuleNativeName = Object.keys(cfg['resources']['jsModuleNative'])[0];
     assets.unshift({
         name: jsModuleNativeName,
diff --git a/src/Draco.Editor.Web/app/ts/loadThemes.ts b/src/Draco.Editor.Web/app/ts/loadThemes.ts
@@ -5,6 +5,8 @@ import { Registry } from 'monaco-textmate';
 import { wireTmGrammars } from 'monaco-editor-textmate';
 import grammarDefinition from '../generated/draco.tmLanguage.json';
 import { isDarkMode } from './helpers.js';
+
+// dark magic pulled out in an evening.
 export async function loadThemes() {
     const wasmPromise = loadWASM(onigasmWasm.buffer); // https://www.npmjs.com/package/onigasm;
 
