Skip to content

Commit fd883e5

Browse files
cesarParracesarParra
committed
Hiding LWC documentation generation behind a flag.
1 parent 9c7a2cb commit fd883e5

File tree

10 files changed

+38
-20
lines changed

10 files changed

+38
-20
lines changed

‎README.md‎

Lines changed: 22 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -138,24 +138,25 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
138138

139139
#### Flags
140140

141-
| Flag | Alias | Description | Default | Required |
142-
|-----------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|
143-
| `--sourceDir` | `-s` | The directory or directories where the source files are located. | N/A | * |
144-
| `--useSfdxProjectJson` | N/A | Read source directories from `sfdx-project.json` packageDirectories. Cannot be used with `--sourceDir`. | `false` | * |
145-
| `--sfdxProjectPath` | N/A | Path to directory containing `sfdx-project.json` (defaults to current directory). Only used with `--useSfdxProjectJson`. | `process.cwd()` | No |
146-
| `--targetDir` | `-t` | The directory where the generated files will be placed. | `docs` | No |
147-
| `--scope` | `-p` | A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. | `[global]` | No |
148-
| `--customObjectVisibility` | `-v` | Controls which custom objects are documented. Values should be separated by a space. | `[public]` | No |
149-
| `--defaultGroupName` | N/A | The default group name to use when a group is not specified. | `Miscellaneous` | No |
150-
| `--namespace` | N/A | The package namespace, if any. If provided, it will be added to the generated files. | N/A | No |
151-
| `--sortAlphabetically` | N/A | Sorts files appearing in the Reference Guide alphabetically, as well as the members of a class, interface or enum alphabetically. If false, the members will be displayed in the same order as the code. | `false` | No |
152-
| `--includeMetadata ` | N/A | Whether to include the file's meta.xml information: Whether it is active and the API version | `false` | No |
153-
| `--linkingStrategy` | N/A | The strategy to use when linking to other classes. Possible values are `relative`, `no-link`, and `none` | `relative` | No |
154-
| `--customObjectsGroupName` | N/A | The name under which custom objects will be grouped in the Reference Guide | `Custom Objects` | No |
155-
| `--triggersGroupName` | N/A | The name under which triggers will be grouped in the Reference Guide | `Triggers` | No |
156-
| `--lwcGroupName` | N/A | The name under which Lightning Web Components will be grouped in the Reference Guide | `Triggers` | No |
157-
| `--includeFieldSecurityMetadata` | N/A | Whether to include the compliance category and security classification for fields in the generated files. | `false` | No |
158-
| `--includeInlineHelpTextMetadata` | N/A | Whether to include the inline help text for fields in the generated files. | `false` | No |
141+
| Flag | Alias | Description | Default | Required |
142+
|-----------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|----------|
143+
| `--sourceDir` | `-s` | The directory or directories where the source files are located. | N/A | * |
144+
| `--useSfdxProjectJson` | N/A | Read source directories from `sfdx-project.json` packageDirectories. Cannot be used with `--sourceDir`. | `false` | * |
145+
| `--sfdxProjectPath` | N/A | Path to directory containing `sfdx-project.json` (defaults to current directory). Only used with `--useSfdxProjectJson`. | `process.cwd()` | No |
146+
| `--targetDir` | `-t` | The directory where the generated files will be placed. | `docs` | No |
147+
| `--scope` | `-p` | A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. | `[global]` | No |
148+
| `--customObjectVisibility` | `-v` | Controls which custom objects are documented. Values should be separated by a space. | `[public]` | No |
149+
| `--defaultGroupName` | N/A | The default group name to use when a group is not specified. | `Miscellaneous` | No |
150+
| `--namespace` | N/A | The package namespace, if any. If provided, it will be added to the generated files. | N/A | No |
151+
| `--sortAlphabetically` | N/A | Sorts files appearing in the Reference Guide alphabetically, as well as the members of a class, interface or enum alphabetically. If false, the members will be displayed in the same order as the code. | `false` | No |
152+
| `--includeMetadata ` | N/A | Whether to include the file's meta.xml information: Whether it is active and the API version | `false` | No |
153+
| `--linkingStrategy` | N/A | The strategy to use when linking to other classes. Possible values are `relative`, `no-link`, and `none` | `relative` | No |
154+
| `--customObjectsGroupName` | N/A | The name under which custom objects will be grouped in the Reference Guide | `Custom Objects` | No |
155+
| `--triggersGroupName` | N/A | The name under which triggers will be grouped in the Reference Guide | `Triggers` | No |
156+
| `--experimentalLwcSupport` | N/A | Whether to document LWC files or not. | `false` | No |
157+
| `--lwcGroupName` | N/A | The name under which Lightning Web Components will be grouped in the Reference Guide | `Lightning Web Components` | No |
158+
| `--includeFieldSecurityMetadata` | N/A | Whether to include the compliance category and security classification for fields in the generated files. | `false` | No |
159+
| `--includeInlineHelpTextMetadata` | N/A | Whether to include the inline help text for fields in the generated files. | `false` | No |
159160

160161
> **Note:** The `*` in the Required column indicates that **one** of the source directory options must be specified:
161162
> - `--sourceDir` (single directory or array of directories)
@@ -339,6 +340,9 @@ providing the subcommand, e.g `apexdocs markdown` or `apexdocs changelog`.
339340

340341
### LWC Documentation Limitations
341342

343+
⚠️ LWC documentation is only enabled when providing the `--experimentalLwcSupport` flag or setting the
344+
`experimentalLwcSupport` property to `true` in the configuration file.
345+
342346
ApexDocs supports generating documentation for Lightning Web Components (LWC) as well, but please
343347
be aware of the following limitations:
344348

‎examples/markdown/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
"sourceDir": "force-app",
1717
"scope": ["global", "public", "protected", "private", "namespaceaccessible"],
1818
"namespace": "ns",
19-
"sortAlphabetically": true
19+
"sortAlphabetically": true,
20+
"experimentalLwcSupport": true
2021
}
2122
}

‎src/__tests__/integration-sfdx-project.spec.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ describe('SFDX Project Integration Tests', () => {
178178
it('should generate documentation for Lightning Web Components', () => {
179179
setupTestProjectWithLWC(testDir);
180180

181-
const command = `node "${apexdocsPath}" markdown --useSfdxProjectJson --targetDir ./docs --scope public`;
181+
const command = `node "${apexdocsPath}" markdown --useSfdxProjectJson --targetDir ./docs --scope public --experimentalLwcSupport`;
182182
const result = execSync(command, {
183183
cwd: testDir,
184184
encoding: 'utf8',

‎src/cli/commands/markdown.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,4 +119,9 @@ export const markdownOptions: Record<keyof CliConfigurableMarkdownConfig, Option
119119
type: 'boolean',
120120
describe: 'Whether to include the inline help text for fields in the generated files.',
121121
},
122+
experimentalLwcSupport: {
123+
type: 'boolean',
124+
describe: 'Enable experimental support for documenting Lightning Web Components (LWC).',
125+
default: markdownDefaults.experimentalLwcSupport,
126+
},
122127
};

‎src/core/markdown/__test__/test-helpers.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ export function generateDocs(bundles: UnparsedSourceBundle[], config?: Partial<M
7676
includeInlineHelpTextMetadata: true,
7777
exclude: [],
7878
lwcGroupName: 'Lightning Web Components',
79+
experimentalLwcSupport: true,
7980
...config,
8081
});
8182
}

‎src/core/markdown/adapters/__tests__/interface-adapter.spec.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ const defaultMarkdownGeneratorConfig: MarkdownGeneratorConfig = {
2626
includeInlineHelpTextMetadata: true,
2727
exclude: [],
2828
excludeTags: [],
29+
experimentalLwcSupport: true
2930
};
3031

3132
describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {

‎src/core/markdown/adapters/__tests__/lwc-adapter.spec.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ describe('LWC Adapter', () => {
2121
exclude: [],
2222
excludeTags: [],
2323
lwcGroupName: 'Lightning Web Components',
24+
experimentalLwcSupport: true
2425
};
2526

2627
describe('lwcMetadataToRenderable', () => {

‎src/core/markdown/generate-docs.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,9 @@ export function generateDocs(unparsedBundles: UnparsedSourceBundle[], config: Ma
8888
);
8989
}),
9090
TE.chain((parsedFiles) => {
91+
if (!config.experimentalLwcSupport) {
92+
return TE.right(parsedFiles);
93+
}
9194
return pipe(
9295
reflectLwcSource(filterLwcFiles(unparsedBundles)),
9396
TE.map((parsedFiles) => parsedFiles.filter((file) => file.type.isExposed)),

‎src/core/shared/types.d.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ export type CliConfigurableMarkdownConfig = {
4545
referenceGuideTitle: string;
4646
includeFieldSecurityMetadata: boolean;
4747
includeInlineHelpTextMetadata: boolean;
48+
experimentalLwcSupport: boolean;
4849
};
4950

5051
export type UserDefinedMarkdownConfig = {

‎src/defaults.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ export const markdownDefaults = {
2222
excludeTags: [],
2323
includeFieldSecurityMetadata: false,
2424
includeInlineHelpTextMetadata: false,
25+
experimentalLwcSupport: false,
2526
};
2627

2728
export const openApiDefaults = {

0 commit comments

Comments
 (0)