JSDoc是否支持条件忽略？能否按环境配置控制文档生成

Great question! This is absolutely achievable with JSDoc—you just need to add a bit of custom logic to filter which symbols get included based on your environment. Here are two straightforward ways to make your pseudo-code idea work:

Method 1: Custom JSDoc Plugin #

JSDoc supports custom plugins that hook into its parsing workflow. We can build a simple plugin that reads your environment variable, then adjusts which @ignore if tags get activated.

Step 1: Create the Plugin File #

Make a new file (e.g., jsdoc-env-ignore.js) with this code:

exports.handlers = {
  // Run this before JSDoc parses your source code
  beforeParse: function(event) {
    // Grab the current environment (default to 'dev' if not set)
    const currentEnv = process.env.NODE_ENV || 'dev';
    
    // Replace matching @ignore if [env] tags with standard @ignore
    event.source = event.source.replace(
      /\/\*\*[\s\S]*?@ignore if (\w+)[\s\S]*?\*\//g,
      (fullMatch, targetEnv) => {
        // If the tag's environment matches the current one, mark it to ignore
        if (targetEnv === currentEnv) {
          return fullMatch.replace(`@ignore if ${targetEnv}`, '@ignore');
        }
        // Otherwise, leave the comment as-is (no ignore)
        return fullMatch;
      }
    );
  }
};

Step 2: Update JSDoc Config #

Add the plugin to your JSDoc configuration file (e.g., jsdoc.json):

{
  "plugins": ["./jsdoc-env-ignore.js"],
  // Add your other JSDoc settings here (source paths, output directory, etc.)
}

Step 3: Generate Docs by Environment #

Run JSDoc with the desired environment variable:

• For dev (only generate var b docs, since var a has @ignore if dev):

  NODE_ENV=dev jsdoc -c jsdoc.json
  

• For prod (only generate var a docs, since var b has @ignore if prod):

  NODE_ENV=prod jsdoc -c jsdoc.json
  

Method 2: Preprocessing Script (No Plugin Needed) #

If you don't want to mess with JSDoc plugins, you can preprocess your source code to adjust the comments before feeding it to JSDoc.

Step 1: Create the Preprocessing Script #

Make a file (e.g., preprocess-docs.js) with this code:

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

// Get environment and target file from command line
const currentEnv = process.env.NODE_ENV || 'dev';
const targetFile = process.argv[2];
const tempFile = path.join(__dirname, 'temp-docs-source.js');

// Read and modify the source code
let sourceContent = fs.readFileSync(targetFile, 'utf8');
sourceContent = sourceContent.replace(
  /\/\*\*([\s\S]*?)@ignore if (\w+)([\s\S]*?)\*\//g,
  (fullMatch, preComment, targetEnv, postComment) => {
    if (targetEnv === currentEnv) {
      // Add @ignore to skip this symbol
      return `/**${preComment}@ignore${postComment}*/`;
    } else {
      // Remove the @ignore if tag so JSDoc documents it
      return `/**${preComment}${postComment}*/`;
    }
  }
);

// Write modified content to a temp file
fs.writeFileSync(tempFile, sourceContent);

// Run JSDoc on the temp file
execSync(`jsdoc ${tempFile}`, { stdio: 'inherit' });

// Clean up the temp file
fs.unlinkSync(tempFile);

Step 2: Generate Docs by Environment #

Run the script with your source file and desired environment:

• Dev environment:

  NODE_ENV=dev node preprocess-docs.js your-source-file.js
  

• Prod environment:

  NODE_ENV=prod node preprocess-docs.js your-source-file.js
  

Both methods will give you the environment-specific documentation you're looking for. The plugin approach is cleaner for long-term use, while the preprocessing script is great for quick one-off setups.

内容的提问来源于stack exchange，提问作者FabianTe