generateJsdoc: Skip JSDoc processing if no input resources have been …

…located

Prominent example: theme libraries

lib/tasks/jsdoc/executeJsdocSdkTransformation.js

@@ -1,4 +1,4 @@
-const log = require("@ui5/logger").getLogger("builder:tasks:executeJsdocSdkTransformation");
+const log = require("@ui5/logger").getLogger("builder:tasks:jsdoc:executeJsdocSdkTransformation");
 const ReaderCollectionPrioritized = require("@ui5/fs").ReaderCollectionPrioritized;
 const fsInterface = require("@ui5/fs").fsInterface;
 const sdkTransformer = require("../../processors/jsdoc/sdkTransformer");

lib/tasks/jsdoc/generateJsdoc.js

@@ -1,3 +1,4 @@
+const log = require("@ui5/logger").getLogger("builder:tasks:jsdoc:generateJsdoc");
 const path = require("path");
 const makeDir = require("make-dir");
 const fs = require("graceful-fs");
@@ -28,10 +29,9 @@ const generateJsdoc = async function({workspace, dependencies, options} = {}) {
 
  const {sourcePath: resourcePath, targetPath, tmpPath} = await generateJsdoc._createTmpDirs(options.projectName);
 
- await Promise.all([
+ const [writtenResourcesCount] = await Promise.all([
  generateJsdoc._writeResourcesToDir({
  workspace,
- dependencies,
  pattern: options.pattern,
  targetPath: resourcePath
  }),
@@ -41,6 +41,12 @@ const generateJsdoc = async function({workspace, dependencies, options} = {}) {
  })
  ]);
 
+ if (writtenResourcesCount === 0) {
+ log.info(`Failed to find any input resources for project ${options.projectName} using pattern ` +
+ `${options.pattern}. Skipping JSDoc generation...`);
+ return;
+ }
+
  const createdResources = await jsdocGenerator({
  sourcePath: resourcePath,
  targetPath,
@@ -121,7 +127,7 @@ function createTmpDir(projectName, keep = false) {
  * @param {module:@ui5/fs.DuplexCollection} parameters.workspace DuplexCollection to read and write files
  * @param {string} parameters.pattern Pattern to match resources in workspace against
  * @param {string} parameters.targetPath Path to write the resources to
- * @returns {Promise<undefined>} Promise resolving with <code>undefined</code> once data has been written
+ * @returns {Promise<number>} Promise resolving with number of resources written to given directory
  */
 async function writeResourcesToDir({workspace, pattern, targetPath}) {
  const fsTarget = resourceFactory.createAdapter({
@@ -138,6 +144,7 @@ async function writeResourcesToDir({workspace, pattern, targetPath}) {
 
  // write all resources to the tmp folder
  await Promise.all(allResources.map((resource) => fsTarget.write(resource)));
+ return allResources.length;
 }
 
 /**
@@ -147,7 +154,7 @@ async function writeResourcesToDir({workspace, pattern, targetPath}) {
  * @param {Object} parameters Parameters
  * @param {module:@ui5/fs.AbstractReader} parameters.dependencies Reader or Collection to read dependency files
  * @param {string} parameters.targetPath Path to write the resources to
- * @returns {Promise<undefined>} Promise resolving with <code>undefined</code> once data has been written
+ * @returns {Promise<number>} Promise resolving with number of resources written to given directory
  */
 async function writeDependencyApisToDir({dependencies, targetPath}) {
  const depApis = await dependencies.byGlob("/test-resources/**/designtime/api.json");
@@ -164,6 +171,7 @@ async function writeDependencyApisToDir({dependencies, targetPath}) {
  virBasePath: "/"
  });
  await Promise.all(apis.map((resource) => fsTarget.write(resource)));
+ return apis.length;
 }
 
 module.exports = generateJsdoc;

test/lib/tasks/jsdoc/generateJsdoc.js

@@ -183,8 +183,8 @@ test.serial("generateJsdoc", async (t) => {
  targetPath: "/some/target/path",
  tmpPath: "/some/tmp/path",
  });
- const writeResourcesToDirStub = sinon.stub(generateJsdoc, "_writeResourcesToDir").resolves();
- const writeDependencyApisToDirStub = sinon.stub(generateJsdoc, "_writeDependencyApisToDir").resolves();
+ const writeResourcesToDirStub = sinon.stub(generateJsdoc, "_writeResourcesToDir").resolves(1);
+ const writeDependencyApisToDirStub = sinon.stub(generateJsdoc, "_writeDependencyApisToDir").resolves(0);
 
  const writeStub = sinon.stub().resolves();
  const workspace = {
@@ -208,7 +208,6 @@ test.serial("generateJsdoc", async (t) => {
  t.deepEqual(writeResourcesToDirStub.callCount, 1, "writeResourcesToDir got called once");
  t.deepEqual(writeResourcesToDirStub.getCall(0).args[0], {
  workspace,
- dependencies: "dependencies",
  pattern: "some pattern",
  targetPath: "/some/source/path" // one's target is another one's source
  }, "writeResourcesToDir got called with correct arguments");
@@ -239,6 +238,50 @@ test.serial("generateJsdoc", async (t) => {
  mock.stop("../../../../lib/processors/jsdoc/jsdocGenerator");
 });
 
+test.serial("generateJsdoc with missing resources", async (t) => {
+ const jsdocGeneratorStub = sinon.stub().resolves();
+ mock("../../../../lib/processors/jsdoc/jsdocGenerator", jsdocGeneratorStub);
+ const logger = require("@ui5/logger");
+ const infoLogStub = sinon.stub();
+ const myLoggerInstance = {
+ info: infoLogStub
+ };
+ sinon.stub(logger, "getLogger").returns(myLoggerInstance);
+ const generateJsdoc = mock.reRequire("../../../../lib/tasks/jsdoc/generateJsdoc");
+
+ sinon.stub(generateJsdoc, "_createTmpDirs").resolves({
+ sourcePath: "/some/source/path",
+ targetPath: "/some/target/path",
+ tmpPath: "/some/tmp/path",
+ });
+ sinon.stub(generateJsdoc, "_writeResourcesToDir").resolves(0);
+ sinon.stub(generateJsdoc, "_writeDependencyApisToDir").resolves(0);
+
+ const writeStub = sinon.stub().resolves();
+ const workspace = {
+ write: writeStub
+ };
+ await generateJsdoc({
+ workspace,
+ dependencies: "dependencies",
+ options: {
+ pattern: "some pattern",
+ projectName: "some.project",
+ namespace: "some/project",
+ version: "some version"
+ }
+ });
+
+ t.deepEqual(infoLogStub.callCount, 1, "One message has been logged");
+ t.deepEqual(infoLogStub.getCall(0).args[0], "Failed to find any input resources for project some.project " +
+ "using pattern some pattern. Skipping JSDoc generation...",
+ "Correct message has been logged");
+
+ t.deepEqual(jsdocGeneratorStub.callCount, 0, "jsdocGenerator processor has *not* been called");
+
+ mock.stop("../../../../lib/processors/jsdoc/jsdocGenerator");
+});
+
 test.serial("generateJsdoc missing parameters", async (t) => {
  const error = await t.throws(generateJsdoc());
  t.deepEqual(error.message, "[generateJsdoc]: One or more mandatory options not provided",