[Doc] buildpack ref docs

packages/pwa-buildpack/lib/BuildBus/BuildBus.js

@@ -22,17 +22,15 @@ const busCache = new Map();
 const INVOKE_FLAG = Symbol.for('FORCE_BUILDBUS_CREATE_FACTORY');
 
 /**
- * Manager of dependencies' participation in project builds and tasks. Broker
- * for dependencies with Targets to interact with each other.
- *
+ * Manages dependency participation in project builds and tasks.
+ * It executes their declare and intercept files so they can interact with each other.
  */
 class BuildBus extends Trackable {
     /**
      * Remove the cached BuildBus for the given context.
      *
      * @static
      * @param {string} context - Root directory whose BuildBus to delete.
-     * @returns {undefined}
      */
     static clear(context) {
         const absContext = path.resolve(context);
@@ -42,15 +40,18 @@ class BuildBus extends Trackable {
      * Remove all cached BuildBus objects.
      *
      * @static
-     * @returns {undefined}
      */
     static clearAll() {
         busCache.clear();
     }
     /**
      * Get or create the BuildBus for the given context.
-     * This factory is the supported way to construct BuildBuses.
-     * It caches BuildBuses and connects them to the logging infrastructure.
+     * This factory is the supported way to construct BuildBus instances.
+     * It caches the instances and connects them to the logging infrastructure.
+     * 
+     * Only one BuildBus is active for a project root directory (context) at any given time.
+     * This way, Buildpack code can retrieve the BuildBus for a context even if the bus
+     * instance hasn't been sent as a parameter.
      *
      * @example <caption>Get or create the BuildBus for the package.json file in `./project-dir`, then bind targets, then call a target.</caption>
      * ```js
@@ -59,7 +60,7 @@ class BuildBus extends Trackable {
      * bus.getTargetsOf('my-extension').myTarget.call();
      * ```
      *
-     * @param {string} context - Root directory whose BuildBus to get or create.
+     * @param {string} context - Root directory of the BuildBus to get or create.
      * @returns {BuildBus}
      */
     static for(context) {
@@ -118,8 +119,8 @@ class BuildBus extends Trackable {
         return `pwa-studio.targets.${phase}`;
     }
     /**
-     * Method which connects TargetProviders to each other. BuildBus passes
-     * this method to TargetProvider as its `getExternalTargets` callback.
+     * Connects TargetProviders to each other. BuildBus passes
+     * this method to TargetProvider as its `getExternalTargets()` callback.
      *
      * @private
      * @param {Object} requestor - Dependency requesting the targets.
@@ -148,18 +149,18 @@ class BuildBus extends Trackable {
      * `targets.of()` methods.
      *
      * @param {string} depName - Dependency whose targets to retrieve.
-     * @returns {Object.<(string, Target)>} TargetProvider for the dependency.
+     * @returns {Object.<string, Target>} TargetProvider for the dependency.
      */
     getTargetsOf(depName) {
         return this._getTargets(depName).own;
     }
     /**
      * Run the two defined phases, `declare` and `intercept`, in order.
      * This binds all targets which the BuildBus can find by analyzing
-     * dependencies in the project package file..
+     * dependencies in the project package file.
      *
      * @chainable
-     * @returns Returns the instance (chainable).
+     * @returns {BuildBus} Returns this instance (chainable).
      */
     init() {
         this.runPhase('declare');

packages/pwa-buildpack/lib/BuildBus/Target.js

@@ -17,8 +17,9 @@ const interceptionTypes = {
  * Target instead of the literal Tapable instance. This enables
  * better logging, error checking, and validation.
  *
- * @class Target
  * @extends {Trackable}
+ * 
+ * @see [Tapable docs]{@link https://github.com/webpack/tapable}
  */
 class Target extends Trackable {
     static get SOURCE_SEP() {
@@ -67,7 +68,10 @@ class Target extends Trackable {
      * provided arguments. Returns the final value if it's a Waterfall target,
      * or the value returned by the first interceptor that returns a value if
      * it's a Bail target.
-     * @memberof Target
+     * 
+     * @param {...*} [args] All arguments are passed to the interceptor functions that have tapped this Target.
+     * 
+     * @return {*} Returns whatever the underlying Tapable Hook returns.
      */
     call(...args) {
         this.track('beforeCall', { type: 'sync', args });
@@ -82,7 +86,10 @@ class Target extends Trackable {
      * order. Last argument must be a callback. It will be invoked when all
      * interceptors have run, or when the first returning interceptor has run
      * if it's a Bail target.
-     * @memberof Target
+     * 
+     * @param {...*} args All arguments **except the last argument** are passed to the interceptor functions that have tapped this Target. The last argument must be a callback function, which will receive the final output of the interceptors.
+     * 
+     * @return {undefined} `callAsync` returns nothing, instead passing any output of the interceptors as the first argument of the callback.
      */
     callAsync(...incomingArgs) {
         const callbackIndex = incomingArgs.length - 1;
@@ -99,7 +106,10 @@ class Target extends Trackable {
      * Run `.intercept(options)` on the underlying Tapable Hook.
      * Can register meta-interceptors for other activity on this target.
      * Use only for logging and debugging.
-     * @memberof Target
+     * 
+     * @param {object} options Options for [Tapable#intercept](https://github.com/webpack/tapable#interception).
+     * 
+     * @return {void}
      */
     intercept(options) {
         this.track('intercept', {
@@ -115,6 +125,10 @@ class Target extends Trackable {
      * the Target type, calls interceptors in parallel or in series. Returns a
      * promise. It will be fulfilled when all interceptors have run, or when
      * the first returning interceptor has run if it's a Bail target.
+     * 
+     * @param {...*} [args] All arguments are passed to the interceptor functions that have tapped this Target.
+     * 
+     * @return {Promise} A Promise for any output of the target's interceptors.
      */
     promise(...args) {
         this.track('beforeCall', { type: 'promise', args });
@@ -124,17 +138,45 @@ class Target extends Trackable {
         });
     }
     /**
-     *
+     *  Adds a synchronous interceptor to the target.
+     *  If you just supply a function, it will use your extension's package name as the name of the tap.
+     * 
+     * 
+     * @param {(string|object)} [name] string or object containing the name of the interceptor (optional)
+     * @param {function} interceptor interceptor function
+     * 
+     * @return {undefined}
      */
     tap(name, interceptor) {
         return this._invokeTap('tap', name, interceptor);
     }
+    /**
+     *  Adds an callback-style asynchronous interceptor to the Target. The interceptor will receive a callback function as its last argument. Only supported on Async targets.
+     * 
+     * @param {string|object} name string or object containing the name of the interceptor
+     * @param {function} interceptor interceptor function
+     * 
+     * @return {undefined}
+     */
     tapAsync(name, interceptor) {
         return this._invokeTap('tapAsync', name, interceptor);
     }
+    /**
+     *  Adds a Promise-returning async interceptor to the Target. The interceptor may return a Promise, which the Target will resolve. Only supported on Async targets.
+     * 
+     * @param {string|object} name string or object containing the name of the interceptor
+     * @param {function} interceptor interceptor function
+     * 
+     * @return {undefined}
+     */
     tapPromise(name, interceptor) {
         return this._invokeTap('tapPromise', name, interceptor);
     }
+    /**
+     * Provides the JSON object representation of this target
+     * 
+     * @returns {object} JSON object
+     */
     toJSON() {
         const json = super.toJSON();
         if (json) {

packages/pwa-buildpack/lib/BuildBus/TargetProvider.js

@@ -10,34 +10,41 @@ const {
 } = require('./mapHooksToTargets');
 
 /**
- * Respond to a request from a {@link TargetProvider} to retrieve a different
- * (external) TargetProvider. When using a TargetProvider disconnected from a
- * {@link BuildBus}, this callback is necessary if anything requests external
- * targets on the TargetProvider using {@link TargetProvider#of}.
+ * Respond to a request from a [TargetProvider]{@link https://pwastudio.io/pwa-buildpack/reference/buildbus/targetprovider/}
+ * to retrieve a different(external) TargetProvider.
+ * 
+ * This callback pattern helps to loosely couple TargetProviders so
+ * they are more testable.
+ * 
  * @callback getExternalTargets
  * @param {TargetProvider} requestor - TargetProvider making the request.
  * @param {string} requested - External targets being requested.
  * @returns {TargetProvider} TargetProvider for the requested targets.
  */
 
 /**
- * Mediates between a BuildBus and an "extension" package participating in the
- * BuildBus declare/intercept lifecycle. The `targets` object used by declare
- * and intercept functions is a TargetProvider. Each extension receives its own
- * TargetProvider, which provides methods for declaring its own targets,
- * intercepting its own targets, and intercepting the targets of other
- * extensions.
+ * Handles interactions between a BuildBus and an "extension" package
+ * participating in the BuildBus declare/intercept lifecycle.
+ *
+ * The `targets` object used by declare and intercept functions is a TargetProvider.
+ * Each extension receives its own TargetProvider, which provides methods for
+ * declaring its own targets, intercepting its own targets, and intercepting the
+ * targets of other extensions.
  *
- * @class TargetProvider
  * @extends {Trackable}
  */
 class TargetProvider extends Trackable {
     /**
      * Creates an instance of TargetProvider.
-     * @param {BuildBus|function} bus - BuildBus using this TargetProvider. Alternately, can be a function which will be used for logging.
+     * 
+     * @constructs
+     *
+     * @param {BuildBus|function} bus - BuildBus using this TargetProvider, or, when testing, a logging function.
      * @param {Object} dep - The package which owns this TargetProvider.
      * @param {string} dep.name - Name of the package which owns this.
-     * @param {getExternalTargets} getExternalTargets - Function this TargetProvider will use to retrieve external packages when they are requested with `.of()`. Should usually be a delegate to {@link BuildBus#_requestTargets}
+     * @param {getExternalTargets} getExternalTargets - Function this TargetProvider will use to retrieve external packages when they are requested with `.of()`.
+     * Should usually be a delegate to BuildBus's [`getExternalTargets()`]{@link http://pwastudio.io/pwa-buildpack/reference/buildbus/targetprovider/#buildpackbuildbusgetexternaltargets--targetprovider}
+     * 
      * @memberof TargetProvider
      */
     constructor(bus, dep, getExternalTargets) {
@@ -72,13 +79,12 @@ class TargetProvider extends Trackable {
         );
     }
     /**
-     * Call in the declare phase to register targets that this package and
+     * Call this function in the declare phase to register targets that this package and
      * other packages can intercept.
      *
      * @param {Object.<string,Target>} declarations - An object whose keys are
      * the names of targets to declare, and whose properties are newly
      * constructed Targets.
-     * @memberof TargetProvider
      */
     declare(declarations) {
         if (this.phase !== 'declare') {
@@ -117,14 +123,13 @@ class TargetProvider extends Trackable {
         }
     }
     /**
-     * Call in the intercept phase to get the targets of other packages, which
-     * can then be intercepted by calling `.tap` methods on them.
+     * Call this function in the intercept phase to get the targets of other packages, which
+     * can then be intercepted by calling `.tap()` methods on them.
      *
      * @param {string} depName - The package whose targets you want to retrieve.
      * @returns {Object.<string,Target>} - An object whose keys are the names
      * of the requested package's targets, and whose values are the target
      * objects.
-     * @memberof TargetProvider
      */
     of(depName) {
         if (this.phase !== 'intercept') {
@@ -166,7 +171,7 @@ class TargetProvider extends Trackable {
 /**
  * Constructors for the different Target classes.
  * @memberof TargetProvider
- * @type {Object.<string,Tapable.Hook}
+ * @type {Object.<string,Tapable.Hook>}
  */
 TargetProvider.prototype.types = types;