docs(developer): kmc-package api documentation

developer/docs/api/etc/kmc-package.api.md

@@ -14,30 +14,38 @@ import { KeymanCompilerResult } from '@keymanapp/common-types';
 import { KmpJsonFile } from '@keymanapp/common-types';
 import { KpsFile } from '@keymanapp/common-types';
 
-// @public (undocumented)
+// @public
 export class KmpCompiler implements KeymanCompiler {
+    // @internal
     buildKmpFile(kpsFilename: string, kmpJsonData: KmpJsonFile.KmpJsonFile): Promise<Uint8Array>;
-    // Warning: (ae-forgotten-export) The symbol "KmpCompilerOptions" needs to be exported by the entry point main.d.ts
-    //
-    // (undocumented)
     init(callbacks: CompilerCallbacks, options: KmpCompilerOptions): Promise<boolean>;
-    // (undocumented)
+    // @internal (undocumented)
     loadKpsFile(kpsFilename: string): KpsFile.KpsFile;
-    // Warning: (ae-forgotten-export) The symbol "KmpCompilerResult" needs to be exported by the entry point main.d.ts
-    //
-    // (undocumented)
     run(inputFilename: string, outputFilename?: string): Promise<KmpCompilerResult>;
-    // (undocumented)
+    // @internal (undocumented)
     transformKpsFileToKmpObject(kpsFilename: string, kps: KpsFile.KpsFile): KmpJsonFile.KmpJsonFile;
-    // (undocumented)
+    // @internal (undocumented)
     transformKpsToKmpObject(kpsFilename: string): KmpJsonFile.KmpJsonFile;
-    // Warning: (ae-forgotten-export) The symbol "KmpCompilerArtifacts" needs to be exported by the entry point main.d.ts
-    //
-    // (undocumented)
     write(artifacts: KmpCompilerArtifacts): Promise<boolean>;
 }
 
-// @public (undocumented)
+// @public
+export interface KmpCompilerArtifacts extends KeymanCompilerArtifacts {
+    kmp: KeymanCompilerArtifact;
+}
+
+// @public
+export interface KmpCompilerOptions extends CompilerOptions {
+}
+
+// @public
+export interface KmpCompilerResult extends KeymanCompilerResult {
+    artifacts: KmpCompilerArtifacts;
+}
+
+// Warning: (ae-internal-missing-underscore) The name "PackageCompilerMessages" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal (undocumented)
 export class PackageCompilerMessages {
     // (undocumented)
     static ERROR_FileCouldNotBeRead: number;
@@ -220,30 +228,38 @@ export class PackageCompilerMessages {
     }) => CompilerEvent;
 }
 
-// @public (undocumented)
+// Warning: (ae-internal-missing-underscore) The name "PackageValidation" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal (undocumented)
 export class PackageValidation {
     constructor(callbacks: CompilerCallbacks, options: CompilerOptions);
     // (undocumented)
     validate(filename: string, kmpJson: KmpJsonFile.KmpJsonFile): boolean;
 }
 
-// @public (undocumented)
+// @public
 export class WindowsPackageInstallerCompiler implements KeymanCompiler {
-    // Warning: (ae-forgotten-export) The symbol "WindowsPackageInstallerCompilerOptions" needs to be exported by the entry point main.d.ts
-    //
-    // (undocumented)
     init(callbacks: CompilerCallbacks, options: WindowsPackageInstallerCompilerOptions): Promise<boolean>;
-    // Warning: (ae-forgotten-export) The symbol "WindowsPackageInstallerCompilerResult" needs to be exported by the entry point main.d.ts
-    //
-    // (undocumented)
     run(inputFilename: string, outputFilename?: string): Promise<WindowsPackageInstallerCompilerResult>;
-    // Warning: (ae-forgotten-export) The symbol "WindowsPackageInstallerCompilerArtifacts" needs to be exported by the entry point main.d.ts
-    //
-    // (undocumented)
     write(artifacts: WindowsPackageInstallerCompilerArtifacts): Promise<boolean>;
 }
 
-// @public (undocumented)
+// @public
+export interface WindowsPackageInstallerCompilerArtifacts extends KeymanCompilerArtifacts {
+    exe: KeymanCompilerArtifact;
+}
+
+// @public
+export interface WindowsPackageInstallerCompilerOptions extends KmpCompilerOptions {
+    sources: WindowsPackageInstallerSources;
+}
+
+// @public
+export interface WindowsPackageInstallerCompilerResult extends KeymanCompilerResult {
+    artifacts: WindowsPackageInstallerCompilerArtifacts;
+}
+
+// @public
 export interface WindowsPackageInstallerSources {
     // (undocumented)
     appName?: string;

developer/src/kmc-package/src/compiler/kmp-compiler.ts

@@ -21,29 +21,76 @@ const KMP_INF_FILENAME = 'kmp.inf';
 // this filename for existing keyboard packages.
 const WELCOME_HTM_FILENAME = 'welcome.htm';
 
+/**
+ * @public
+ * Options for the .kps compiler
+ */
 export interface KmpCompilerOptions extends CompilerOptions {
   // Note: WindowsPackageInstallerCompilerOptions extends KmpCompilerOptions, so
   // be careful when modifying this interface
 };
 
+/**
+ * @public
+ * Internal in-memory build artifacts from a successful compilation
+ */
 export interface KmpCompilerArtifacts extends KeymanCompilerArtifacts {
+  /**
+   * Binary keyboard package filedata and filename - installable into Keyman
+   * desktop and mobile projects
+   */
   kmp: KeymanCompilerArtifact;
 };
 
+/**
+ * @public
+ * Build artifacts from the .kps compiler
+ */
 export interface KmpCompilerResult extends KeymanCompilerResult {
+  /**
+   * Internal in-memory build artifacts from a successful compilation. Caller
+   * can write these to disk with {@link KmpCompiler.write}
+   */
   artifacts: KmpCompilerArtifacts;
 };
 
+/**
+ * @public
+ * Compiles a .kps file to a .kmp archive. The compiler does not read or write
+ * from filesystem or network directly, but relies on callbacks for all external
+ * IO.
+ */
 export class KmpCompiler implements KeymanCompiler {
   private callbacks: CompilerCallbacks;
   private options: KmpCompilerOptions;
 
+  /**
+   * Initialize the compiler.
+   * Copies options.
+   * @param callbacks - Callbacks for external interfaces, including message
+   *                    reporting and file io
+   * @param options   - Compiler options
+   * @returns false if initialization fails
+   */
   public async init(callbacks: CompilerCallbacks, options: KmpCompilerOptions): Promise<boolean> {
     this.callbacks = callbacks;
     this.options = options ? {...options} : {};
     return true;
   }
 
+  /**
+   * Compiles a .kps file to .kmp file. Returns an object containing binary
+   * artifacts on success. The files are passed in by name, and the compiler
+   * will use callbacks as passed to the {@link KmpCompiler.init} function
+   * to read any input files by disk.
+   * @param infile  - Path to source file. Path will be parsed to find relative
+   *                  references in the .kmn file, such as icon or On Screen
+   *                  Keyboard file
+   * @param outfile - Path to output file. The file will not be written to, but
+   *                  will be included in the result for use by
+   *                  {@link KmpCompiler.write}.
+   * @returns         Binary artifacts on success, null on failure.
+   */
   public async run(inputFilename: string, outputFilename?: string): Promise<KmpCompilerResult> {
     const kmpJsonData = this.transformKpsToKmpObject(inputFilename);
     if(!kmpJsonData) {
@@ -80,11 +127,24 @@ export class KmpCompiler implements KeymanCompiler {
     return result;
   }
 
+  /**
+   * Write artifacts from a successful compile to disk, via callbacks methods.
+   * The artifacts written may include:
+   *
+   * - .kmp file - binary keyboard package used by Keyman on desktop and touch
+   *   platforms
+   *
+   * @param artifacts - object containing artifact binary data to write out
+   * @returns true on success
+   */
   public async write(artifacts: KmpCompilerArtifacts): Promise<boolean> {
     this.callbacks.fs.writeFileSync(artifacts.kmp.filename, artifacts.kmp.data);
     return true;
   }
 
+  /**
+   * @internal
+   */
   public transformKpsToKmpObject(kpsFilename: string): KmpJsonFile.KmpJsonFile {
     const kps = this.loadKpsFile(kpsFilename);
     if(!kps) {
@@ -105,6 +165,9 @@ export class KmpCompiler implements KeymanCompiler {
     return kmp;
   }
 
+  /**
+   * @internal
+   */
   public loadKpsFile(kpsFilename: string): KpsFile.KpsFile {
     // Load the KPS data from XML as JS structured data.
     const buffer = this.callbacks.loadFile(kpsFilename);
@@ -136,6 +199,9 @@ export class KmpCompiler implements KeymanCompiler {
     return kps;
   }
 
+  /**
+   * @internal
+   */
   public transformKpsFileToKmpObject(kpsFilename: string, kps: KpsFile.KpsFile): KmpJsonFile.KmpJsonFile {
 
     //
@@ -401,6 +467,7 @@ export class KmpCompiler implements KeymanCompiler {
   }
 
   /**
+   * @internal
    * Returns a Promise to the serialized data which can then be written to a .kmp file.
    *
    * @param kpsFilename - Filename of the kps, not read, used only for calculating relative paths

developer/src/kmc-package/src/compiler/package-compiler-messages.ts

@@ -7,6 +7,9 @@ const SevWarn = CompilerErrorSeverity.Warn | Namespace;
 const SevError = CompilerErrorSeverity.Error | Namespace;
 const SevFatal = CompilerErrorSeverity.Fatal | Namespace;
 
+/**
+ * @internal
+ */
 export class CompilerMessages {
   static FATAL_UnexpectedException = SevFatal | 0x0001;
   static Fatal_UnexpectedException = (o:{e: any}) => CompilerMessageSpecWithException(this.FATAL_UnexpectedException, null, o.e ?? 'unknown error');

developer/src/kmc-package/src/compiler/package-validation.ts

@@ -16,6 +16,9 @@ const MODEL_ID_PATTERN_PACKAGE = /^[a-z_][a-z0-9_]*\.[a-z_][a-z0-9_-]*\.[a-z_][a
 const CONTENT_FILE_BASENAME_PATTERN = /^[a-z0-9_+.-]+$/i; // base names can be case insensitive
 const CONTENT_FILE_EXTENSION_PATTERN = /^(\.[a-z0-9_-]+)?$/;  // extensions should be lower-case or empty
 
+/**
+ * @internal
+ */
 export class PackageValidation {
 
   constructor(private callbacks: CompilerCallbacks, private options: CompilerOptions) {

developer/src/kmc-package/src/compiler/windows-package-installer-compiler.ts

@@ -19,6 +19,10 @@ import { CompilerMessages } from "./package-compiler-messages.js";
 const SETUP_INF_FILENAME = 'setup.inf';
 const PRODUCT_NAME = 'Keyman';
 
+/**
+ * @public
+ * Sources and metadata for the Windows package installer compiler
+ */
 export interface WindowsPackageInstallerSources {
   msiFilename: string;
   setupExeFilename: string;
@@ -30,30 +34,81 @@ export interface WindowsPackageInstallerSources {
   startWithConfiguration: boolean;
 };
 
+/**
+ * @public
+ * Options for the .kps Windows package installer compiler
+ */
 export interface WindowsPackageInstallerCompilerOptions extends KmpCompilerOptions {
+  /**
+   * Sources and metadata for the Windows package installer compiler
+   */
   sources: WindowsPackageInstallerSources;
 }
 
+/**
+ * @public
+ * Internal in-memory build artifacts from a successful compilation
+ */
 export interface WindowsPackageInstallerCompilerArtifacts extends KeymanCompilerArtifacts {
+  /**
+   * Binary package installer filedata and filename - installable into Keyman
+   * desktop and mobile projects
+   */
   exe: KeymanCompilerArtifact;
 };
 
+/**
+ * @public
+ * Build artifacts from the .kps Windows package installer compiler
+ */
 export interface WindowsPackageInstallerCompilerResult extends KeymanCompilerResult {
+  /**
+   * Internal in-memory build artifacts from a successful compilation. Caller
+   * can write these to disk with {@link WindowsPackageInstallerCompiler.write}
+   */
   artifacts: WindowsPackageInstallerCompilerArtifacts;
 };
 
+/**
+ * @public
+ * Compiles a .kps file to a .exe installer. The compiler does not read or write
+ * from filesystem or network directly, but relies on callbacks for all external
+ * IO.
+ */
 export class WindowsPackageInstallerCompiler implements KeymanCompiler {
   private kmpCompiler: KmpCompiler;
   private callbacks: CompilerCallbacks;
   private options: WindowsPackageInstallerCompilerOptions;
 
+  /**
+   * Initialize the compiler.
+   * Copies options.
+   * @param callbacks - Callbacks for external interfaces, including message
+   *                    reporting and file io
+   * @param options   - Compiler options
+   * @returns false if initialization fails
+   */
   async init(callbacks: CompilerCallbacks, options: WindowsPackageInstallerCompilerOptions): Promise<boolean> {
     this.callbacks = callbacks;
     this.options = {...options};
     this.kmpCompiler = new KmpCompiler();
     return await this.kmpCompiler.init(callbacks, options);
   }
 
+  /**
+   * Compiles a .kps file to .exe Windows package installer file. Returns an
+   * object containing binary artifacts on success. The files are passed in by
+   * name, and the compiler will use callbacks as passed to the
+   * {@link WindowsPackageInstallerCompiler.init} function to read any input
+   * files by disk.
+   * @param infile  - Path to source file. Path will be parsed to find relative
+   *                  references in the .kmn file, such as icon or On Screen
+   *                  Keyboard file
+   * @param outfile - Path to output file. The file will not be written to, but
+   *                  will be included in the result for use by
+   *                  {@link WindowsPackageInstallerCompiler.write}.
+   * @returns         Binary artifacts on success, null on failure.
+   */
   public async run(inputFilename: string, outputFilename?: string): Promise<WindowsPackageInstallerCompilerResult> {
     const sources = this.options.sources;
     const kps = this.kmpCompiler.loadKpsFile(inputFilename);
@@ -103,6 +158,15 @@ export class WindowsPackageInstallerCompiler implements KeymanCompiler {
     return result;
   }
 
+  /**
+   * Write artifacts from a successful compile to disk, via callbacks methods.
+   * The artifacts written may include:
+   *
+   * - .exe file - binary Windows package installer executable file
+   *
+   * @param artifacts - object containing artifact binary data to write out
+   * @returns true on success
+   */
   public async write(artifacts: WindowsPackageInstallerCompilerArtifacts): Promise<boolean> {
     this.callbacks.fs.writeFileSync(artifacts.exe.filename, artifacts.exe.data);
     return true;

developer/src/kmc-package/src/main.ts

@@ -1,4 +1,10 @@
-export { KmpCompiler } from "./compiler/kmp-compiler.js";
+export { KmpCompiler, KmpCompilerOptions, KmpCompilerResult, KmpCompilerArtifacts } from "./compiler/kmp-compiler.js";
 export { PackageValidation } from "./compiler/package-validation.js";
-export { WindowsPackageInstallerSources, WindowsPackageInstallerCompiler } from "./compiler/windows-package-installer-compiler.js";
+export {
+  WindowsPackageInstallerSources,
+  WindowsPackageInstallerCompiler,
+  WindowsPackageInstallerCompilerOptions,
+  WindowsPackageInstallerCompilerResult,
+  WindowsPackageInstallerCompilerArtifacts,
+} from "./compiler/windows-package-installer-compiler.js";
 export { CompilerMessages as PackageCompilerMessages } from './compiler/package-compiler-messages.js';