doc(addBuildPhase): add notes & supporting typedef

Author: erisu

lib/pbxProject.js

@@ -30,6 +30,56 @@ const parser = require('./parser/pbxproj');
 const plist = require('simple-plist');
 const COMMENT_KEY = /_comment$/;
 
+// MARK: Start of Typings
+
+/**
+ * A list of known build phase types.
+ * @typedef {'PBXCopyFilesBuildPhase' |
+ *  'PBXResourcesBuildPhase' |
+ *  'PBXFrameworksBuildPhase' |
+ *  'PBXHeadersBuildPhase' |
+ *  'PBXShellScriptBuildPhase' |
+ *  'PBXSourcesBuildPhase'
+ * } BuildPhaseType
+ */
+
+/**
+ * The result object returned when adding a build phase.
+ * @typedef {object} AddBuildPhaseResults
+ * @property {string} uuid Build Phase UUID
+ * @property {object} buildPhase Build Phase object
+ */
+
+/**
+ * A list of valid target types used for copy files build configurations.
+ * @typedef {'application'
+ *  | 'app_extension'
+ *  | 'bundle'
+ *  | 'command_line_tool'
+ *  | 'dynamic_library'
+ *  | 'framework'
+ *  | 'frameworks'
+ *  | 'static_library'
+ *  | 'unit_test_bundle'
+ *  | 'watch_app'
+ *  | 'watch2_app'
+ *  | 'watch_extension'
+ *  | 'watch2_extension'
+ * } CopyFilesTargetType
+ */
+
+/**
+ * Options used when adding a PBXShellScriptBuildPhase.
+ * @typedef {object} ShellScriptOptions
+ * @property {string[]} inputPaths input paths
+ * @property {string[]} outputPaths output Paths
+ * @property {string} shellPath shell paths
+ * @property {0 | 1} runOnlyForDeploymentPostprocessing run script for install builds only
+ * @property {1} [alwaysOutOfDate] disables dependency analysis when set to true
+ */
+
+// MARK: End of Typings
+
 function PBXProject (filename) {
     if (!(this instanceof PBXProject)) { return new PBXProject(filename); }
 
@@ -851,6 +901,25 @@ PBXProject.prototype.addTargetDependency = function (target, dependencyTargets)
     return { uuid: target, target: nativeTargets[target] };
 };
 
+/**
+ * Add files to specific build phase by defining the build phase type.
+ *
+ * @example
+ * // Adding a file to Resource Build Phase.
+ * myProject.addBuildPhase(
+ *   ['MyAssets.xcassets'],
+ *   'PBXResourcesBuildPhase',
+ *   'Resources'
+ * );
+ *
+ * @param {string[]} filePathsArray collection of file paths
+ * @param {BuildPhaseType} buildPhaseType target build phase
+ * @param {string} comment name of the build phase. (e.g. "Copy My Files")
+ * @param {string} target UUID of the PBXNativeTarget (defaults to first target)
+ * @param {CopyFilesTargetType|ShellScriptOptions} optionsOrFolderType either sell script options or copy files target type
+ * @param {string} subfolderPath copy files subfolder path (default: "")
+ * @returns {AddBuildPhaseResults} object containing the build phase & uuid
+ */
 PBXProject.prototype.addBuildPhase = function (filePathsArray, buildPhaseType, comment, target, optionsOrFolderType, subfolderPath) {
     let buildPhaseSection;
     const fileReferenceSection = this.pbxFileReferenceSection();