4. Configuring which files to document

There are several strategies you can use to choose which files should be picked up for documentation.

Ignored files

ApexDocs respects the Salesforce .forceignore file. Any pattern included in the .forceignore file will be excluded from the documentation.

Using the ignore annotation

You can tell ApexDoc to skip over an Apex file by adding the @ignore annotation at the top of the definition.

Example

/**
 * @ignore
 */
public class MyClass {
    public static void myMethod() {
    }
}

Using glob patterns

You can exclude one or multiple files from being documented by providing a list of glob patterns to the exclude property in the configuration file.

import { defineMarkdownConfig } from "@cparra/apexdocs";

export default defineMarkdownConfig({
  sourceDir: 'force-app',
  targetDir: 'docs',
  scope: ['global', 'public'],
  exclude: ['**/MyClass.cls', '**/MyOtherClass.cls'],
  ...
});

You can also leverage the exclude property to indirectly modify things like custom metadata records you do not want included in the custom metadata type object documentation.

//...
exclude: ['**/*.md-meta.xml']
//...

Using configuration Hooks

You can use configuration hooks to skip over certain file in a programmatic way based on custom logic.

The transformDocs hook sends over all files that will be documented, which allows you to filter over them and return a reduced list of files to document.

import { defineMarkdownConfig } from "@cparra/apexdocs";

export default defineMarkdownConfig({
  //...
  transformDocs: async(docs) => {
    // Filter over undersirable documents.
  }
});

For example, say you wanted to skip all files that do not have any ApexDocs set up. One way you can do this is by leveraging the @cparra/apex-reflection (this is the same library that ApexDocs uses under the hook to parse Apex code) library to check if a file has docs set up.

1. Install @cparra/apex-reflection

npm install -D @cparra/apex-reflection

2. Configure the config file as follows

import { defineChangelogConfig, defineMarkdownConfig, DocPageData } from '../../src';
import * as fs from 'node:fs';
import { reflect } from '@cparra/apex-reflection';

// Checks if a document has ApexDocs configured by reading its source file and parsing
// its contents through the apex-reflection library
function hasDocs(doc: DocPageData) {
  if (!('filePath' in doc.source)) {
    return false;
  }

  if (!doc.source.filePath) return false;
  const fileContents = fs.readFileSync(doc.source.filePath!, 'utf-8');
  const parsed = reflect(fileContents);
  return !!parsed.typeMirror?.docComment;
}

export default defineMarkdownConfig({
  transformDocs: async (docs) => {
    return docs.filter(hasDocs); // filters out any doc without ApexDocs configured.
  },
});