@cparra/apexdocs 2.21.0 → 2.23.0-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -16
- package/apexdocs.config.ts +3 -1
- package/docs/types/Classes/nspc.AnotherInterface.md +15 -0
- package/docs/types/Classes/nspc.ChildClass.md +97 -79
- package/docs/types/Main/nspc.SampleClass.md +189 -189
- package/examples/force-app/main/default/classes/AnotherInterface.cls +11 -0
- package/examples/force-app/main/default/classes/ChildClass.cls +12 -0
- package/lib/cli/generate.js +7 -1
- package/lib/cli/generate.js.map +1 -1
- package/lib/model/markdown-file.d.ts +1 -1
- package/lib/model/markdown-file.js +2 -2
- package/lib/model/markdown-file.js.map +1 -1
- package/lib/model/markdown-generation-util/doc-comment-annotation-util.d.ts +1 -0
- package/lib/model/markdown-generation-util/doc-comment-annotation-util.js +17 -2
- package/lib/model/markdown-generation-util/doc-comment-annotation-util.js.map +1 -1
- package/lib/model/markdown-generation-util/field-declaration-util.js +1 -9
- package/lib/model/markdown-generation-util/field-declaration-util.js.map +1 -1
- package/lib/model/markdown-generation-util/method-declaration-util.js +1 -0
- package/lib/model/markdown-generation-util/method-declaration-util.js.map +1 -1
- package/lib/model/markdown-generation-util/type-declaration-util.js +1 -0
- package/lib/model/markdown-generation-util/type-declaration-util.js.map +1 -1
- package/lib/model/markdown-type-file.js +1 -9
- package/lib/model/markdown-type-file.js.map +1 -1
- package/lib/service/walkers/class-walker.js +6 -6
- package/lib/service/walkers/class-walker.js.map +1 -1
- package/lib/service/walkers/enum-walker.js.map +1 -1
- package/lib/service/walkers/interface-walker.js +1 -1
- package/lib/service/walkers/interface-walker.js.map +1 -1
- package/lib/service/walkers/walker.d.ts +3 -0
- package/lib/service/walkers/walker.js +7 -0
- package/lib/service/walkers/walker.js.map +1 -1
- package/lib/settings.d.ts +11 -0
- package/lib/settings.js +10 -0
- package/lib/settings.js.map +1 -1
- package/lib/transpiler/markdown/class-file-generatorHelper.js +2 -2
- package/lib/transpiler/markdown/class-file-generatorHelper.js.map +1 -1
- package/lib/transpiler/markdown/jekyll/jekyll-docsProcessor.d.ts +2 -1
- package/lib/transpiler/markdown/jekyll/jekyll-docsProcessor.js +26 -3
- package/lib/transpiler/markdown/jekyll/jekyll-docsProcessor.js.map +1 -1
- package/package.json +1 -1
- package/src/cli/generate.ts +6 -0
- package/src/model/markdown-file.ts +2 -2
- package/src/model/markdown-generation-util/doc-comment-annotation-util.ts +16 -0
- package/src/model/markdown-generation-util/field-declaration-util.ts +3 -9
- package/src/model/markdown-generation-util/method-declaration-util.ts +3 -1
- package/src/model/markdown-generation-util/type-declaration-util.ts +3 -1
- package/src/model/markdown-type-file.ts +4 -10
- package/src/service/walkers/class-walker.ts +6 -7
- package/src/service/walkers/enum-walker.ts +0 -1
- package/src/service/walkers/interface-walker.ts +1 -1
- package/src/service/walkers/walker.ts +8 -1
- package/src/settings.ts +21 -0
- package/src/transpiler/markdown/class-file-generatorHelper.ts +2 -2
- package/src/transpiler/markdown/jekyll/jekyll-docsProcessor.ts +26 -3
- package/ROADMAP.md +0 -16
package/README.md
CHANGED
|
@@ -102,22 +102,23 @@ apexdocs-generate
|
|
|
102
102
|
|
|
103
103
|
The CLI supports the following parameters:
|
|
104
104
|
|
|
105
|
-
| Parameter
|
|
106
|
-
|
|
107
|
-
| --sourceDir
|
|
108
|
-
| --targetDir
|
|
109
|
-
| --recursive
|
|
110
|
-
| --scope
|
|
111
|
-
| --targetGenerator
|
|
112
|
-
| --indexOnly
|
|
113
|
-
| --defaultGroupName
|
|
114
|
-
| --sanitizeHtml
|
|
115
|
-
| --openApiTitle
|
|
116
|
-
| --title
|
|
117
|
-
| --namespace
|
|
118
|
-
| --openApiFileName
|
|
119
|
-
| --
|
|
120
|
-
| --
|
|
105
|
+
| Parameter | Alias | Description | Default | Required |
|
|
106
|
+
|-----------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|----------|
|
|
107
|
+
| --sourceDir | -s | The directory location which contains your apex .cls classes. | N/A | Yes |
|
|
108
|
+
| --targetDir | -t | The directory location where documentation will be generated to. | `docs` | No |
|
|
109
|
+
| --recursive | -r | Whether .cls classes will be searched for recursively in the directory provided. | `true` | No |
|
|
110
|
+
| --scope | -p | A list of scopes to document. Values should be separated by a space, e.g --scope public private. Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource. | `global` | No |
|
|
111
|
+
| --targetGenerator | -g | Define the static file generator for which the documents will be created. Currently supports: `jekyll`, `docsify`, `plain-markdown`, and `openapi`. | `jekyll` | No |
|
|
112
|
+
| --indexOnly | N/A | Defines whether only the index file should be generated. | `false` | No |
|
|
113
|
+
| --defaultGroupName | N/A | Defines the `@group` name to be used when a file does not specify it. | `Miscellaneous` | No |
|
|
114
|
+
| --sanitizeHtml | N/A | When on, any special character within your ApexDocs is converted into its HTML code representation. This is specially useful when generic objects are described within the docs, e.g. "List< Foo>", "Map<Foo, Bar>" because otherwise the content within < and > would be treated as HTML tags and not shown in the output. Content in @example blocks are never sanitized. | `Apex REST Api` | No |
|
|
115
|
+
| --openApiTitle | N/A | If using "openapi" as the target generator, this allows you to specify the OpenApi title value. | true | No |
|
|
116
|
+
| --title | N/A | Allows you to specify the home page main title. If using "openapi" this acts as an alias to the openApiTitle parameter | `Classes` | No |
|
|
117
|
+
| --namespace | N/A | The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. If generating an OpenApi definition, it will be added to the file's Server Url. | N/A | No |
|
|
118
|
+
| --openApiFileName | N/A | If using "openapi" as the target generator, this allows you to specify the name of the output file. | `openapi` | No |
|
|
119
|
+
| --sortMembersAlphabetically | N/A | Whether to sort the members of a class alphabetically. | `false` | No |
|
|
120
|
+
| --includeMetadata | N/A | Whether to include the file's meta.xml information: Whether it is active and and the API version | false | No |
|
|
121
|
+
| --documentationRootDir | N/A | The root directory where the documentation will be generated. This is useful when you want to generate the documentation in a subdirectory of your project. | N/A | No |
|
|
121
122
|
|
|
122
123
|
### Using a configuration file
|
|
123
124
|
|
|
@@ -142,6 +143,16 @@ allow you to override some of the default behavior:
|
|
|
142
143
|
The full object definition can be imported from `@cparra/apexdocs/lib/settings`
|
|
143
144
|
- `onAfterProcess` - A function that will be called after all files have been processed. It receives a `TargetFile[]` array
|
|
144
145
|
with all of the files that were processed and does not return anything.
|
|
146
|
+
- `frontMatterHeader` - A function that will be called before the front matter is written to the file (when using the Jekyll generator).
|
|
147
|
+
It receives a `TargetType` object
|
|
148
|
+
and should return a list of strings that will be written to the file as the front matter.
|
|
149
|
+
The full object definition can be imported from `@cparra/apexdocs/lib/settings`
|
|
150
|
+
and contains the following properties:
|
|
151
|
+
- `name` - The name of the type
|
|
152
|
+
- `typeName` - Can be 'class', 'interface', or 'enum'
|
|
153
|
+
- `accessModifier` - The access modifier of the type
|
|
154
|
+
- `group` - The group to which the type belongs (if any)
|
|
155
|
+
- `description` - The description of the type as defined in the ApexDoc
|
|
145
156
|
|
|
146
157
|
```typescript
|
|
147
158
|
import {TargetFile} from "@cparra/apexdocs/lib/settings";
|
|
@@ -357,6 +368,31 @@ To fix this issue, when not sanitizing HTML, you should wrap any code that conta
|
|
|
357
368
|
treated as HTML within '\`'
|
|
358
369
|
or within `<code>` tags.
|
|
359
370
|
|
|
371
|
+
### Displaying diagrams
|
|
372
|
+
|
|
373
|
+
You can display diagrams in your documentation by leveraging Github's built-in [Mermaid](https://mermaid-js.github.io/mermaid/#/) support.
|
|
374
|
+
|
|
375
|
+
If you are using a markdown generator that supports Mermaid (e.g. [Github's markdown](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/),
|
|
376
|
+
you can add diagrams to your documentation by using the
|
|
377
|
+
`@mermaid` tag.
|
|
378
|
+
|
|
379
|
+
**Example**
|
|
380
|
+
|
|
381
|
+
```apex
|
|
382
|
+
/**
|
|
383
|
+
* @mermaid
|
|
384
|
+
* graph TD
|
|
385
|
+
* A[Christmas] -->|Get money| B(Go shopping)
|
|
386
|
+
* B --> C{Let me think}
|
|
387
|
+
* C -->|One| D[Laptop]
|
|
388
|
+
* C -->|Two| E[iPhone]
|
|
389
|
+
* C -->|Three| F[Car]
|
|
390
|
+
*/
|
|
391
|
+
public class MyClass {
|
|
392
|
+
}
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
[Here's an example of how that looks](/docs/types/Classes/nspc.AnotherInterface.md)
|
|
360
396
|
|
|
361
397
|
### Ignoring files and members
|
|
362
398
|
|
package/apexdocs.config.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { TargetFile } from './src/settings';
|
|
1
|
+
import { TargetFile, TargetType } from './src/settings';
|
|
2
2
|
|
|
3
3
|
export default {
|
|
4
4
|
onBeforeFileWrite: (file: TargetFile): TargetFile => {
|
|
@@ -8,4 +8,6 @@ export default {
|
|
|
8
8
|
onAfterProcess: (files: TargetFile[]) => {
|
|
9
9
|
console.log('onAfterProcess files', files);
|
|
10
10
|
},
|
|
11
|
+
frontMatterHeader: (file: TargetType) => [`title: ${file.name}.cls`, `description: ${file.description}`],
|
|
12
|
+
sortMembersAlphabetically: true,
|
|
11
13
|
};
|
|
@@ -5,3 +5,18 @@ Some desc
|
|
|
5
5
|
|
|
6
6
|
**Group** Classes
|
|
7
7
|
|
|
8
|
+
|
|
9
|
+
```mermaid
|
|
10
|
+
sequenceDiagram
|
|
11
|
+
participant dotcom
|
|
12
|
+
participant iframe
|
|
13
|
+
participant viewscreen
|
|
14
|
+
dotcom->>iframe: loads html w/ iframe url
|
|
15
|
+
iframe->>viewscreen: request template
|
|
16
|
+
viewscreen->>iframe: html & javascript
|
|
17
|
+
iframe->>dotcom: iframe ready
|
|
18
|
+
dotcom->>iframe: set mermaid data on iframe
|
|
19
|
+
iframe->>iframe: render mermaid
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
|
|
@@ -1,79 +1,97 @@
|
|
|
1
|
-
# nspc.ChildClass
|
|
2
|
-
|
|
3
|
-
Some desc
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
**Inheritance**
|
|
7
|
-
|
|
8
|
-
[nspc.GrandparentClass](types/Misc-Group/nspc.GrandparentClass.md)
|
|
9
|
-
>
|
|
10
|
-
[nspc.ParentClass](types/Misc-Group/nspc.ParentClass.md)
|
|
11
|
-
>
|
|
12
|
-
ChildClass
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
**Implemented types**
|
|
16
|
-
|
|
17
|
-
[nspc.SampleInterface](types/Sample-Interfaces/nspc.SampleInterface.md)
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
**Group** Classes
|
|
21
|
-
|
|
22
|
-
## Fields
|
|
23
|
-
|
|
24
|
-
### `private
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
### `
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
1
|
+
# nspc.ChildClass
|
|
2
|
+
|
|
3
|
+
Some desc
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
**Inheritance**
|
|
7
|
+
|
|
8
|
+
[nspc.GrandparentClass](types/Misc-Group/nspc.GrandparentClass.md)
|
|
9
|
+
>
|
|
10
|
+
[nspc.ParentClass](types/Misc-Group/nspc.ParentClass.md)
|
|
11
|
+
>
|
|
12
|
+
ChildClass
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
**Implemented types**
|
|
16
|
+
|
|
17
|
+
[nspc.SampleInterface](types/Sample-Interfaces/nspc.SampleInterface.md)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
**Group** Classes
|
|
21
|
+
|
|
22
|
+
## Fields
|
|
23
|
+
|
|
24
|
+
### `private aPrivateString` → `String`
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
### `private privateStringFromChild` → `String`
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
### `protected protectedGrandParentField` → `String`
|
|
31
|
+
|
|
32
|
+
*Inherited*
|
|
33
|
+
|
|
34
|
+
### `protected protectedStringFromParent` → `String`
|
|
35
|
+
|
|
36
|
+
*Inherited*
|
|
37
|
+
|
|
38
|
+
This is a protected string, use carefully.
|
|
39
|
+
|
|
40
|
+
### `public publicStringFromParent` → `String`
|
|
41
|
+
|
|
42
|
+
*Inherited*
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
## Properties
|
|
46
|
+
|
|
47
|
+
### `protected AProp` → `String`
|
|
48
|
+
|
|
49
|
+
*Inherited*
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
## Methods
|
|
53
|
+
### `public void doSomething()`
|
|
54
|
+
### `public void execute()`
|
|
55
|
+
|
|
56
|
+
Executes the command.
|
|
57
|
+
|
|
58
|
+
### `public String getValue()`
|
|
59
|
+
|
|
60
|
+
Returns a value based on the executed command.
|
|
61
|
+
|
|
62
|
+
#### Returns
|
|
63
|
+
|
|
64
|
+
|Type|Description|
|
|
65
|
+
|---|---|
|
|
66
|
+
|`String`|The value|
|
|
67
|
+
|
|
68
|
+
### `public virtual String overridableMethod()`
|
|
69
|
+
|
|
70
|
+
*Inherited*
|
|
71
|
+
|
|
72
|
+
### `public override String overridableMethodOverridden()`
|
|
73
|
+
|
|
74
|
+
This method was overridden.
|
|
75
|
+
|
|
76
|
+
#### Returns
|
|
77
|
+
|
|
78
|
+
|Type|Description|
|
|
79
|
+
|---|---|
|
|
80
|
+
|`String`|A String.|
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
```mermaid
|
|
84
|
+
sequenceDiagram
|
|
85
|
+
participant dotcom
|
|
86
|
+
participant iframe
|
|
87
|
+
participant viewscreen
|
|
88
|
+
dotcom->>iframe: loads html w/ iframe url
|
|
89
|
+
iframe->>viewscreen: request template
|
|
90
|
+
viewscreen->>iframe: html & javascript
|
|
91
|
+
iframe->>dotcom: iframe ready
|
|
92
|
+
dotcom->>iframe: set mermaid data on iframe
|
|
93
|
+
iframe->>iframe: render mermaid
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
---
|