Improve transform documentation. (#295)

lib/util/transform.js

@@ -9,6 +9,16 @@ const OOOTransform = require('./out-of-order-transform');
 
 class YoResolveError extends WError {}
 
+/**
+ * Transform api should be avoided by generators without a executable.
+ * May break between major yo versions.
+ *
+ * Creates a out of order transform.
+ *
+ * @param {Function} transform - transform function.
+ * @param {Object}   options   - additional options passed to transform
+ * @return {Stream} a transform stream.
+ */
 function createFileTransform(
   transform = (file, _enc, cb) => cb(null, file),
   options = {}
@@ -22,6 +32,9 @@ function createFileTransform(
 }
 
 /**
+ * Transform api should be avoided by generators without a executable.
+ * May break between major yo versions.
+ *
  * Detect if the file is modified
  * See https://github.com/SBoudrias/mem-fs-editor/blob/3ff18e26c52dc30d8f371bcc72c1884f2ea706d6/lib/actions/commit.js#L38
  *
@@ -33,6 +46,9 @@ function fileIsModified(file) {
 }
 
 /**
+ * Transform api should be avoided by generators without a executable.
+ * May break between major yo versions.
+ *
  * Create a for each file stream transform.
  * @param {Function} forEach - Function to execute for each file
  * @param {Object} options - Options
@@ -83,10 +99,17 @@ function parseYoAttributesFile(yoAttributeFileName) {
   );
 }
 
+/**
+ * Transform api should be avoided by generators without a executable.
+ * May break between major yo versions.
+ */
 function createConflicterCheckTransform(conflicter) {
   return createEachFileTransform(file => conflicter.checkForCollision(file), {logName: 'environment:conflicter-check'});
 }
 
+/**
+ * @private
+ */
 function getConflicterStatusForFile(conflicter, filePath, yoAttributeFileName = '.yo-resolve') {
   const fileDir = path.dirname(filePath);
   conflicter.yoResolveByFile = conflicter.yoResolveByFile || {};
@@ -121,6 +144,9 @@ function getConflicterStatusForFile(conflicter, filePath, yoAttributeFileName =
 }
 
 /**
+ * Transform api should be avoided by generators without a executable.
+ * May break between major yo versions.
+ *
  * Create a yo-resolve transform stream.
  * Suports pre-defined conflicter actions action based on file glob.
  * @param {Conflicter} conflicter - Conflicter instance
@@ -134,6 +160,9 @@ function createYoResolveTransform(conflicter, yoResolveFileName) {
 }
 
 /**
+ * Transform api should be avoided by generators without a executable.
+ * May break between major yo versions.
+ *
  * Create a force yeoman configs transform stream.
  * @return {Transform} A Transform https://nodejs.org/api/stream.html#stream_class_stream_transform
  */
@@ -148,6 +177,9 @@ function createYoRcTransform() {
 }
 
 /**
+ * Transform api should be avoided by generators without a executable.
+ * May break between major yo versions.
+ *
  * Create a transform to apply conflicter status.
  * @param {Log} logger - Log reference. See log.js
  * @return {Transform} A Transform https://nodejs.org/api/stream.html#stream_class_stream_transform
@@ -175,10 +207,18 @@ function createConflicterStatusTransform() {
   }, {autoForward: false, logName: 'environment:conflicter-status'});
 }
 
+/**
+ * Transform api should be avoided by generators without a executable.
+ * May break between major yo versions.
+ */
 function createModifiedTransform() {
   return createEachFileTransform({forwardUmodified: false, logName: 'environment:modified'});
 }
 
+/**
+ * Transform api should be avoided by generators without a executable.
+ * May break between major yo versions.
+ */
 function createCommitTransform(memFsEditor) {
   return createFileTransform(file => memFsEditor.commitFileAsync(file), {logName: 'environment:commit'});
 }