WPS-13 docs(comments): better formatting for in code documentation

conf/karma/karma.config.js

@@ -2,8 +2,11 @@ const path = require('path');
 
 // Karma configuration
 module.exports = (config, webpack) => {
-	webpack.devtool = 'inline-source-map';
-	// webpack.devtool = 'cheap-module-source-map'; // cheap-module-source-map - suggested in React: https://reactjs.org/docs/cross-origin-errors.html
+	/**
+	 * cheap-module-source-map - fixing react cross origin suggested in:
+	 * @see https://reactjs.org/docs/cross-origin-errors.html
+	 */
+	webpack.devtool = 'cheap-module-source-map';
 	webpack.module.rules.push({
 		test: /\.(j|t)sx?$/,
 		use: {
@@ -20,36 +23,51 @@ module.exports = (config, webpack) => {
 		// base path that will be used to resolve all patterns (eg. files, exclude)
 		basePath: '',
 
-		// frameworks to use
-		// available frameworks: https://npmjs.org/browse/keyword/karma-adapter
+		/**
+		 * frameworks to use
+		 * available frameworks:
+		 * @see https://npmjs.org/browse/keyword/karma-adapter
+		 */
 		frameworks: ['jasmine'],
 
 		// list of files / patterns to load in the browser
 		files: [
 			// { pattern: './src/**/*.spec.js', watched: false },
 			// { pattern: './src/**/*.spec.ts', watched: false },
-			// Alternative usage one entry point https://github.com/webpack-contrib/karma-webpack#alternative-usage
+			/**
+			 * Alternative usage one entry point:
+			 * @see https://github.com/webpack-contrib/karma-webpack#alternative-usage
+			 */
 			'./src/main.test.js',
 		],
 
 		// list of files / patterns to exclude
 		exclude: [
 		],
 
-		// preprocess matching files before serving them to the browser
-		// available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
+		/**
+		 * preprocess matching files before serving them to the browser
+		 * available preprocessors:
+		 * @see https://npmjs.org/browse/keyword/karma-preprocessor
+		 */
 		preprocessors: {
 			// './src/**/*.spec.js': ['webpack', 'sourcemap'],
 			// './src/**/*.spec.ts': ['webpack', 'sourcemap'],
-			// Alternative usage one entry point https://github.com/webpack-contrib/karma-webpack#alternative-usage
+			/**
+			 * Alternative usage one entry point
+			 * @see https://github.com/webpack-contrib/karma-webpack#alternative-usage
+			 */
 			'./src/main.test.js': ['webpack', 'sourcemap'],
 		},
 
 		webpack,
 
-		// test results reporter to use
-		// possible values: 'dots', 'progress'
-		// available reporters: https://npmjs.org/browse/keyword/karma-reporter
+		/**
+		 * test results reporter to use
+		 * possible values: 'dots', 'progress'
+		 * available reporters:
+		 * @see https://npmjs.org/browse/keyword/karma-reporter
+		 */
 		reporters: [
 			'progress',
 			'kjhtml',
@@ -79,11 +97,17 @@ module.exports = (config, webpack) => {
 		// enable / disable watching file and executing tests whenever any file changes
 		autoWatch: true,
 
-		// start these browsers
-		// available browser launchers: https://npmjs.org/browse/keyword/karma-launcher
+		/**
+		 * start these browsers
+		 * available browser launchers:
+		 * @see https://npmjs.org/browse/keyword/karma-launcher
+		 */
 		browsers: ['Chrome'],
 
-		// fix typescript serving video/mp2t mime type
+		/**
+		 * fix typescript serving video/mp2t mime type
+		 * @see https://github.com/angular/angular-cli/issues/2125#issuecomment-247395088
+		 */
 		mime: {
 			'text/x-typescript': ['ts','tsx']
 		},

conf/webpack/webpack.config.js

@@ -35,7 +35,8 @@ const CopyWebpackPlugin = require('copy-webpack-plugin');
 const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;
 
 /**
- * https://survivejs.com/webpack/styling/eliminating-unused-css/#critical-path-rendering
+ * Order scripts and styles increasing startup speed noticable in google analytics.
+ * @see https://survivejs.com/webpack/styling/eliminating-unused-css/#critical-path-rendering
  */
 const HtmlCriticalPlugin = require("html-critical-webpack-plugin");
 
@@ -79,7 +80,10 @@ const scaffoldConfig = () => {
 	// order of chunks is important for style overriding (more specific styles source later)
 	const chunks = ['vendor', 'styles', 'main'];
 
-	// https://github.com/jantimon/html-webpack-plugin#configuration
+	/**
+	 * Setup generation of html template in which all scripts and styles are included.
+	 * @see https://github.com/jantimon/html-webpack-plugin#configuration
+	 */
 	const htmlPlugin = new HtmlWebpackPlugin({
 		packageConfig,
 		data: {
@@ -199,27 +203,60 @@ const scaffoldConfig = () => {
 				'process.env.APP': JSON.stringify(config),
 				'process.env.LANGUAGES': JSON.stringify(config.languages),
 			}),
+
+			/**
+			 * For analyzing size and module dependancy.
+			 * @see https://github.com/webpack-contrib/webpack-bundle-analyzer
+			 */
 			analyze ? new BundleAnalyzerPlugin({
 				analyzerMode: 'server',
 				openAnalyzer: true,
 				// statsFilename: path.join(config.outPath, 'stats.json'),
 				generateStatsFile: true,
 			}) : null,
+
+			/**
+			 * Tree shaking minification and other optimizations.
+			 * @see https://github.com/webpack-contrib/uglifyjs-webpack-plugin
+			 */
 			isProd ? new UglifyJsPlugin() : null,
-			// This plugin will cause the relative path of the module to be displayed when HMR is enabled. Suggested for use in development.
-			// https://webpack.js.org/plugins/named-modules-plugin/
-			// Also needed for testing with rewiremock https://github.com/theKashey/rewiremock#to-run-inside-webpack-enviroment
+
+			/**
+			 * This plugin will cause the relative path of the module to be displayed when HMR is enabled. Suggested for use in development.
+			 * @see https://webpack.js.org/plugins/named-modules-plugin/
+			 *
+			 * Also needed for testing with rewiremock
+			 * @see https://github.com/theKashey/rewiremock#to-run-inside-webpack-enviroment
+			 */
 			isDev || hmr || isTest ? new webpack.NamedModulesPlugin() : null,
-			// Needed for development and testing with rewiremock https://github.com/theKashey/rewiremock#to-run-inside-webpack-enviroment
+
+			/**
+			 * Coding without reloading pages requires this plugin.
+			 *
+			 * Additionaly it is required for testing with rewiremock.
+			 * @see https://github.com/theKashey/rewiremock#to-run-inside-webpack-enviroment
+			 */
 			isDev && hmr ? new webpack.HotModuleReplacementPlugin() : null,
-			// Use the NoEmitOnErrorsPlugin to skip the emitting phase whenever there are errors while compiling.
-			// This ensures that no assets are emitted that include errors. The emitted flag in the stats is false for all assets.
+
+			/**
+			 * Use the NoEmitOnErrorsPlugin to skip the emitting phase whenever there are errors while compiling.
+			 * This ensures that no assets are emitted that include errors. The emitted flag in the stats is false for all assets.
+			 */
 			isTest ? null : new webpack.NoEmitOnErrorsPlugin(),
+
+			/**
+			 * For spliting scripts comming from node_modules into seperate chunk `vendor`
+			 * @todo: to be removed in webpack 4
+			 */
 			isTest ? null : new webpack.optimize.CommonsChunkPlugin({
 				name: 'vendor',
 				minChunks: ({ resource }) => /node_modules/.test(resource),
 			}),
-			// needed for rewiremock https://github.com/theKashey/rewiremock#to-run-inside-webpack-enviroment
+
+			/**
+			 * needed for rewiremock
+			 * @see https://github.com/theKashey/rewiremock#to-run-inside-webpack-enviroment
+			 */
 			isTest ? new (require('rewiremock/webpack/plugin'))() : null
 		].filter(p => !!p)
 	};

src/main.test.js

@@ -4,7 +4,7 @@ import Adapter from 'enzyme-adapter-react-16';
 /**
  * Required to import interceptor during tests to prevent:
  * TypeError: Cannot read property 'call' of undefined
- * https://github.com/theKashey/rewiremock#webpack-troubleshooting
+ * @see https://github.com/theKashey/rewiremock#webpack-troubleshooting
  */
 import 'rewiremock/webpack/interceptor';
 
@@ -13,7 +13,7 @@ Enzyme.configure({ adapter: new Adapter() });
 const excludeRegexp = /\..*\/(main|index)\./;
 /**
  * We need to load all test files to be included in karma. And all others to generate test coverage.
- * https://github.com/webpack-contrib/karma-webpack#alternative-usage
+ * @see https://github.com/webpack-contrib/karma-webpack#alternative-usage
  */
 const context = require.context('.', true, /\.(t|j)sx?$/);
 context.keys().filter(p => !excludeRegexp.test(p)).forEach(context);

tsconfig.json

@@ -67,7 +67,7 @@
 		"plugins": [{
 			"name": "tslint-language-service"
 		}],
-		"skipLibCheck": true // hack https://github.com/ReactiveX/rxjs/issues/3031
+		"skipLibCheck": true                      /* hack @see https://github.com/ReactiveX/rxjs/issues/3031 */
 	},
 	"files": [
 		"./src/main.js"