chore: add JSDocs

packages/webpack5/src/helpers/config.ts

@@ -11,6 +11,11 @@ function getCLILib() {
 	return require(env.nativescriptLibPath);
 }
 
+/**
+ * Utility to get a value from the nativescript.config.ts file.
+ *
+ * @param {string} key The key to get from the config. Supports dot-notation.
+ */
 export function getValue<T = any>(key: string): T {
 	const lib = getCLILib();
 

packages/webpack5/src/helpers/copyRules.ts

@@ -7,10 +7,27 @@ import { getEntryDirPath } from './platform';
  */
 export let copyRules = new Set([]);
 
+/**
+ * Utility to add new copy rules. Accepts a glob. For example
+ *  - **\/*.html - copy all .html files found in any sub dir.
+ *  - myFolder/* - copy all files from myFolder
+ *
+ * The path is relative to the folder of the entry file
+ * (specified in the main field of the package.json)
+ *
+ * @param {string} glob
+ */
 export function addCopyRule(glob: string) {
 	copyRules.add(glob);
 }
 
+/**
+ * Utility to remove a copy rule. The glob should be the exact glob
+ * to remove. For example
+ *  - fonts/** - to remove the default copy rule for fonts
+ *
+ * @param {string} glob
+ */
 export function removeCopyRule(glob: string) {
 	copyRules.delete(glob);
 }

packages/webpack5/src/helpers/dependencies.ts

@@ -2,6 +2,12 @@ import { getPackageJson, getProjectRootPath } from './project';
 import path from 'path';
 
 // todo: memoize
+/**
+ * Utility to get all dependencies from the project package.json.
+ * The result combines dependencies and devDependencies
+ *
+ * @returns string[] dependencies
+ */
 export function getAllDependencies(): string[] {
 	const packageJSON = getPackageJson();
 
@@ -12,11 +18,23 @@ export function getAllDependencies(): string[] {
 }
 
 // todo: memoize
+/**
+ * Utility to check if the project has a specific dependency
+ * in either dependencies or devDependencies.
+ *
+ * @param {string} dependencyName
+ * @returns boolean
+ */
 export function hasDependency(dependencyName: string) {
 	return getAllDependencies().includes(dependencyName);
 }
 
 // todo: memoize
+/**
+ * Utility to get the path (usually nested in node_modules) of a dependency.
+ *
+ * @param dependencyName
+ */
 export function getDependencyPath(dependencyName: string): string | null {
 	try {
 		const resolvedPath = require.resolve(`${dependencyName}/package.json`, {

packages/webpack5/src/helpers/externalConfigs.ts

@@ -6,6 +6,9 @@ import { info, warn } from './log';
 import * as lib from '../index';
 import { clearCurrentPlugin, setCurrentPlugin } from '../index';
 
+/**
+ * @internal
+ */
 export function applyExternalConfigs() {
 	getAllDependencies().forEach((dependency) => {
 		const packagePath = getDependencyPath(dependency);

packages/webpack5/src/helpers/flavor.ts

@@ -2,6 +2,10 @@ import { defaultConfigs } from '@nativescript/webpack';
 import { getAllDependencies } from './dependencies';
 import { error } from './log';
 
+/**
+ * Utility to determine the project flavor based on installed dependencies
+ * (vue, angular, react, svelete, typescript, javascript...)
+ */
 export function determineProjectFlavor(): keyof typeof defaultConfigs | false {
 	const dependencies = getAllDependencies();
 

packages/webpack5/src/helpers/platform.ts

@@ -22,15 +22,27 @@ const platforms: {
 	ios: iOSPlatform,
 };
 
+/**
+ * Utility to register a new supported platform.
+ *
+ * @param {string} name The name of the platform (eg. web, desktop)
+ * @param platform A platform definition of the platform specifics
+ */
 export function addPlatform(name: string, platform: INativeScriptPlatform) {
 	console.log('adding platform', name, platform);
 	platforms[name] = platform;
 }
 
+/**
+ * Utility to get the currently targeted platform definition
+ */
 export function getPlatform(): INativeScriptPlatform {
 	return platforms[getPlatformName()];
 }
 
+/**
+ * Utility to get the currently targeted platform name
+ */
 export function getPlatformName(): Platform {
 	if (env?.android) {
 		return 'android';
@@ -62,6 +74,9 @@ export function getPlatformName(): Platform {
 	`);
 }
 
+/**
+ * Utility to get the entry file path for the currently targeted platform
+ */
 export function getEntryPath() {
 	const platform = getPlatform();
 
@@ -76,10 +91,16 @@ export function getEntryPath() {
 	return resolve(getProjectRootPath(), packageJson.main);
 }
 
+/**
+ * Utility to get the entry file directory path for the currently targeted platform
+ */
 export function getEntryDirPath() {
 	return dirname(getEntryPath());
 }
 
+/**
+ * Utility to get the dist file path for the currently targeted platform
+ */
 export function getDistPath() {
 	const platform = getPlatform();
 
@@ -92,6 +113,9 @@ export function getDistPath() {
 	return `platforms/${getPlatformName()}/dist`;
 }
 
+/**
+ * Utility to get the absolute dist file path for the currently targeted platform
+ */
 export function getAbsoluteDistPath() {
 	return resolve(getProjectRootPath(), getDistPath());
 }

packages/webpack5/src/helpers/project.ts

@@ -15,6 +15,9 @@ interface IPackageJson {
 	// todo: add additional fields as we require them
 }
 
+/**
+ * Utility function to get the contents of the project package.json
+ */
 export function getPackageJson() {
 	const packageJsonPath = resolve(getProjectRootPath(), 'package.json');
 

packages/webpack5/src/index.ts

@@ -62,9 +62,22 @@ export function clearCurrentPlugin() {
 }
 
 ////// PUBLIC API
+/**
+ * The default flavor specific configs
+ */
 export const defaultConfigs = configs;
+
+/**
+ * Utilities to simplify various tasks
+ */
 export const Utils = helpers;
 
+/**
+ * Initialize @nativescript/webpack with the webpack env.
+ * Must be called first.
+ *
+ * @param _env The webpack env
+ */
 export function init(_env: IWebpackEnv) {
 	hasInitialized = true;
 	if (_env) {
@@ -72,6 +85,15 @@ export function init(_env: IWebpackEnv) {
 	}
 }
 
+/**
+ * Explicitly specify the base config to use.
+ * Calling this will opt-out from automatic flavor detection.
+ *
+ * Useful when the flavor cannot be detected due to the project structure
+ * for example in a custom monorepo.
+ *
+ * @param config Name of the base config to use.
+ */
 export function useConfig(config: keyof typeof defaultConfigs | false) {
 	explicitUseConfig = true;
 	if (config) {
@@ -82,6 +104,12 @@ export function useConfig(config: keyof typeof defaultConfigs | false) {
 	}
 }
 
+/**
+ * Add a new function to be called when building the internal config using webpack-chain.
+ *
+ * @param chainFn A function that accepts the internal chain config, and the current environment
+ * @param options Optional options to control the order in which the chain function should be applied.
+ */
 export function chainWebpack(
 	chainFn: (config: Config, env: IWebpackEnv) => any,
 	options?: { order?: number }
@@ -93,6 +121,11 @@ export function chainWebpack(
 	});
 }
 
+/**
+ * Merge an object into the resolved chain config.
+ *
+ * @param mergeFn An object or a function that optionally returns an object (can mutate the object directly and return nothing)
+ */
 export function mergeWebpack(
 	mergeFn: (
 		config: Partial<webpack.Configuration>,
@@ -102,6 +135,9 @@ export function mergeWebpack(
 	webpackMerges.push(mergeFn);
 }
 
+/**
+ * Resolve a new instance of the internal chain config with all chain functions applied.
+ */
 export function resolveChainableConfig(): Config {
 	const config = new Config();
 
@@ -144,6 +180,11 @@ export function resolveChainableConfig(): Config {
 	return config;
 }
 
+/**
+ * Resolve a "final" configuration that has all chain functions and merges applied.
+ *
+ * @param chainableConfig Optional chain config to use.
+ */
 export function resolveConfig(
 	chainableConfig = resolveChainableConfig()
 ): webpack.Configuration {

packages/webpack5/src/plugins/PlatformSuffixPlugin.ts

@@ -8,6 +8,17 @@ interface PlatformSuffixPluginOptions {
 	// extensions: string[] | (() => string[])
 }
 
+/**
+ * The platform suffix plugin will try to resolve files with a platform specifier (suffix)
+ * falling back to the non-platform-specific version.
+ *
+ * For example:
+ *   import something from './something.js'
+ *
+ *   will first look for './something.<platform>.js'
+ *   and if not found look for './something.js'
+ *
+ */
 export class PlatformSuffixPlugin {
 	private readonly platform: string;
 	// private readonly extensions: string[]

packages/webpack5/src/transformers/NativeClass/index.ts

@@ -1,5 +1,10 @@
 import ts from 'typescript';
 
+/**
+ * A TypeScript transform that compiles classes marked with @NativeClass as es5 & commonjs
+ *
+ * @param ctx
+ */
 export default function (ctx: ts.TransformationContext) {
 	function isNativeClassExtension(node: ts.ClassDeclaration) {
 		return (