docs: code comments

configs/webpack.config.js

@@ -10,52 +10,64 @@ const CleanWebpackPlugin = require('clean-webpack-plugin');
 module.exports = (env, argv) => {
   return {
     entry: {
+      // bundle root with name app.js
       app: path.resolve(__dirname, "../entries/index.ts"),
     },
     output: {
+      // TravicCI or you can deploy your site from this folder (after `yarn build:release`)
       path: dist,
     },
     devServer: {
       contentBase: dist,
       hot: true,
+      // you can connect to dev server from devices in your network (e.g. 192.168.0.3:3000)
       host: '0.0.0.0',
       port: 3000,
       noInfo: true,
       stats: 'errors-only',
-      // doesn't work? (no errors in html when webpack compilation fails)
+      // doesn't work? (we want to show errors in html when webpack compilation fails)
       overlay: {
         warnings: true,
         errors: true
       }
     },
     plugins: [
+      // show compilation progress bar in console
       new WebpackBar(),
+      // clean dist folder before compilation
       new CleanWebpackPlugin(),
+      // add scripts, css, ... to html template
       new HtmlWebpackPlugin({
         template: path.resolve(__dirname, "../entries/index.html"),
         hash: true
       }),
+      // compile Rust
       new WasmPackPlugin({
         crateDirectory: path.resolve(__dirname, "../crate"),
         // It fails with "index out of bounds" in `development` mode
         // when there are many constants in view template (?)
         forceMode: "production",
       }),
-      // Uncomment if you have problems with Edge and polyfill in index.html isn't enough
+
+
+      // Uncomment when you have problems with Edge (= when small polyfill in index.html doesn't work)
       //
       // Have this example work in Edge which doesn't ship `TextEncoder` or
       // `TextDecoder` at this time.
       // new webpack.ProvidePlugin({
       //   TextDecoder: ['text-encoding', 'TextDecoder'],
       //   TextEncoder: ['text-encoding', 'TextEncoder']
       // }),
+
+      // you can find files from folder ../static on url http://my-site.com/static/
       new CopyWebpackPlugin([
         {
           from: 'static',
           to: 'static'
         }
       ])
     ],
+    // webpack try to guess how to resolve imports in this order:
     resolve: {
       extensions: [ ".ts", ".js", '.wasm']
     },
@@ -67,6 +79,8 @@ module.exports = (env, argv) => {
             {
               loader: 'file-loader',
               options: {
+                // don't copy files to dist, we do it through CopyWebpackPlugin (see above)
+                // - we only want to resolve urls to these files
                 emitFile: false,
                 name: '[path][name].[ext]'
               },
@@ -80,13 +94,19 @@ module.exports = (env, argv) => {
           test: /\.css$/,
           use: [
             'style-loader',
-            { loader: 'css-loader', options: { importLoaders: 1 } },
+            { loader: 'css-loader', options: {
+                // https://github.com/webpack-contrib/css-loader/issues/228
+                importLoaders: 1
+              }
+            },
             {
               loader: 'postcss-loader',
               options: {
                 config: {
-                  ctx: { mode: argv.mode },
-                  path: __dirname
+                  // path to postcss.config.js
+                  path: __dirname,
+                  // send mode into postcss.config.js (see more info in that file)
+                  ctx: { mode: argv.mode }
                 }
               }
             }

configs/webpack.css_classes.config.js

@@ -3,6 +3,10 @@ const path = require("path");
 const WebpackBar = require('webpackbar');
 const CleanWebpackPlugin = require('clean-webpack-plugin');
 
+// Webpack should generate `css_classes.rust` with this config
+// It's used in command `yarn generate:css_classes`
+// See `webpack.config.js` for more info about individual settings
+
 module.exports = (env, argv) => {
   return {
     entry: path.resolve(__dirname, "../entries/index.css_classes.ts"),

crate/src/ts/clock.ts

@@ -1,3 +1,7 @@
+
+// Example of triggering an event in Typescript and handling in Rust (see `../app.rs`)
+// startClock is called from /entries/index.ts
+
 export const startClock = () => {
     dispatchOnClockTickEvent();
 
@@ -9,4 +13,4 @@ export const startClock = () => {
 const dispatchOnClockTickEvent = () => {
     const event = new CustomEvent('on_clock_tick', { detail: (new Date()).toLocaleTimeString() });
     window.dispatchEvent(event);
-}
+}

crate/src/ts/helpers.ts

@@ -1,4 +1,6 @@
 
+// Example of function that is called from Rust (see ../ts_apis.rs)
+
 export const get_random_number = (min: number, max: number): number => {
     return Math.floor(Math.random() * (max - min + 1) ) + min;
-}
+}

crate/src/ts/seed_helpers.ts

@@ -1,7 +1,8 @@
 
+// Seed doesn't use RAF in a native render loop at the time of writing
 export const callRequestAnimationFrame = (): void => {
     requestAnimationFrame(() => {
         const event = new CustomEvent('on_request_animation_frame');
         window.dispatchEvent(event);
     })
-}
+}

css/styles.css

@@ -61,6 +61,7 @@
   * @import "utilities/skew-transforms";
   */
 
+/* Example of custom class */
 .bg-custom {
   background: url("../static/images/decoration.png") no-repeat fixed center top;
 }

entries/index.css_classes.ts

@@ -1 +1,5 @@
+/**
+ * This file is used when `yarn generate:css_classes` is called.
+ * We want to run only pipeline that processes CSS so it generates `css_classes.rs`.
+ */
 import "../css/styles.css";

entries/index.ts

@@ -2,8 +2,8 @@ import "../css/styles.css";
 import { startClock } from  "../crate/src/ts/clock";
 
 (async () => {
-    // we have to load wasm async
-    // NOTE: files in crate/pkg/ exists ONLY after webpack compilation
+    // We have to load wasm async
+    // NOTE: files in crate/pkg/ will be created on first build
     (await import('../crate/pkg/appname')).run();
     startClock();
 })()

scripts/optimize_wasm.js

@@ -7,6 +7,9 @@ const findFiles = require('find')
 // https://www.npmjs.com/package/binaryen#module-optimization
 binaryen.setShrinkLevel(2)
 
+/**
+ * Load, optimize and save all .wasm files in folder `dist`
+ */
 findFiles.eachfile(/\.wasm$/, './dist', file => {
     const wasmModule = binaryen.readBinary(fs.readFileSync(file))
     wasmModule.optimize()

scripts/postcss_rust_helpers.js

@@ -2,8 +2,14 @@ const path = require('path')
 const findFiles = require('find');
 const fs = require('fs');
 
+// Helpers are used by configs/postcss.config.js
+
 module.exports = {
-    // returns Set of class names
+    /**
+     * Search in Rust files for C.class_name
+     *
+     * @returns usedCssClasses Set of class names
+     */
     getUsedCssClasses: function() {
         const usedCssClasses = new Set;
         // search in Rust files
@@ -21,7 +27,13 @@ module.exports = {
         })
         return usedCssClasses
     },
-    // returns string
+    /**
+     * Transform css class name into indentifier that can be used as Rust struct field name
+     * (see https://github.com/MartinKavik/postcss-typed-css-classes/blob/master/generators/rust_generator.js)
+     *
+     * @param {string} name
+     * @returns string Escaped class name
+     */
     escapeClassName: function (name) {
         name = name.replace(/-/g, '_')
         name = name.replace(/:/g, '__')