Skip to content

Commit

Permalink
Merge pull request #114 from cesarParra/alphabetical-sort
Browse files Browse the repository at this point in the history
Introducing a way to sort type members when generating documentation …
  • Loading branch information
cesarParra authored Apr 15, 2024
2 parents 3dc086d a0242b8 commit c629056
Show file tree
Hide file tree
Showing 14 changed files with 87 additions and 78 deletions.
33 changes: 17 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,22 102,23 @@ apexdocs-generate

The CLI supports the following parameters:

| Parameter | Alias | Description | Default | Required |
|------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|----------|
| --sourceDir | -s | The directory location which contains your apex .cls classes. | N/A | Yes |
| --targetDir | -t | The directory location where documentation will be generated to. | `docs` | No |
| --recursive | -r | Whether .cls classes will be searched for recursively in the directory provided. | `true` | No |
| --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 |
| --targetGenerator | -g | Define the static file generator for which the documents will be created. Currently supports: `jekyll`, `docsify`, `plain-markdown`, and `openapi`. | `jekyll` | No |
| --indexOnly | N/A | Defines whether only the index file should be generated. | `false` | No |
| --defaultGroupName | N/A | Defines the `@group` name to be used when a file does not specify it. | `Miscellaneous` | No |
| --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 |
| --openApiTitle | N/A | If using "openapi" as the target generator, this allows you to specify the OpenApi title value. | true | No |
| --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 |
| --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 |
| --openApiFileName | N/A | If using "openapi" as the target generator, this allows you to specify the name of the output file. | `openapi` | No |
| --includeMetadata | N/A | Whether to include the file's meta.xml information: Whether it is active and and the API version | false | No |
| --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 |
| Parameter | Alias | Description | Default | Required |
|-----------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|----------|
| --sourceDir | -s | The directory location which contains your apex .cls classes. | N/A | Yes |
| --targetDir | -t | The directory location where documentation will be generated to. | `docs` | No |
| --recursive | -r | Whether .cls classes will be searched for recursively in the directory provided. | `true` | No |
| --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 |
| --targetGenerator | -g | Define the static file generator for which the documents will be created. Currently supports: `jekyll`, `docsify`, `plain-markdown`, and `openapi`. | `jekyll` | No |
| --indexOnly | N/A | Defines whether only the index file should be generated. | `false` | No |
| --defaultGroupName | N/A | Defines the `@group` name to be used when a file does not specify it. | `Miscellaneous` | No |
| --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 |
| --openApiTitle | N/A | If using "openapi" as the target generator, this allows you to specify the OpenApi title value. | true | No |
| --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 |
| --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 |
| --openApiFileName | N/A | If using "openapi" as the target generator, this allows you to specify the name of the output file. | `openapi` | No |
| --sortMembersAlphabetically | N/A | Whether to sort the members of a class alphabetically. | `false` | No |
| --includeMetadata | N/A | Whether to include the file's meta.xml information: Whether it is active and and the API version | false | No |
| --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 |

### Using a configuration file

Expand Down
1 change: 1 addition & 0 deletions apexdocs.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 9,5 @@ export default {
console.log('onAfterProcess files', files);
},
frontMatterHeader: (file: TargetType) => [`title: ${file.name}.cls`, `description: ${file.description}`],
sortMembersAlphabetically: true,
};
39 changes: 21 additions & 18 deletions docs/types/Classes/nspc.ChildClass.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 21,9 @@ ChildClass

## Fields

### `private aPrivateString``String`


### `private privateStringFromChild``String`


Expand Down Expand Up @@ -48,6 51,24 @@ This is a protected string, use carefully.
---
## Methods
### `public void doSomething()`
### `public void execute()`

Executes the command.

### `public String getValue()`

Returns a value based on the executed command.

#### Returns

|Type|Description|
|---|---|
|`String`|The value|

### `public virtual String overridableMethod()`

*Inherited*

### `public override String overridableMethodOverridden()`

This method was overridden.
Expand All @@ -73,22 94,4 @@ sequenceDiagram
```


### `public void execute()`

Executes the command.

### `public String getValue()`

Returns a value based on the executed command.

#### Returns

|Type|Description|
|---|---|
|`String`|The value|

### `public virtual String overridableMethod()`

*Inherited*

---
26 changes: 13 additions & 13 deletions docs/types/Main/nspc.SampleClass.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,23 62,23 @@ Constructs a SampleClass with an argument.
## Fields
### Common Constants

* `public ANOTHER_CONSTANT``String`
* `public A_CONSTANT``String` [`NAMESPACEACCESSIBLE` ] - This is a constant.
* `public ANOTHER_CONSTANT``String`
* `public listOfStrings``List<String>`
---
### 'General' Constants

* `public GENERAL_ANOTHER_CONSTANT``String`
* `public GENERAL_A_CONSTANT``String` [`NAMESPACEACCESSIBLE` ] - This is a constant.
---
### Other variables

* `public someVariable``String`
* `public GENERAL_ANOTHER_CONSTANT``String`
---
### Other

* `private somePrivateStuff``String`
---
### Other variables

* `public someVariable``String`
---
## Properties

### `public AnotherProp``Decimal`
Expand All @@ -97,6 97,13 @@ This is a String property.
---
## Methods
### A method group
##### `public static String anotherSampleMethod(String arg1)`

Something here


**Arg1** The arg1 description

##### `public static String sampleMethod(String argument1, String argument2)`

`NAMESPACEACCESSIBLE`
Expand All @@ -123,13 130,6 @@ System.debug(result);
```


##### `public static String anotherSampleMethod(String arg1)`

Something here


**Arg1** The arg1 description

##### `public static Map<Id,List<String>> yetAnotherSampleMethod(String arg1)`
---
### Other
Expand Down
1 change: 1 addition & 0 deletions examples/force-app/main/default/classes/ChildClass.cls
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 4,7 @@
*/
public class ChildClass extends ParentClass implements SampleInterface {
private String privateStringFromChild;
private String aPrivateString;

public void doSomething() {
System.debug('Do something');
Expand Down
5 changes: 5 additions & 0 deletions src/cli/generate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 85,10 @@ result.then((config) => {
describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
default: 'openapi',
},
sortMembersAlphabetically: {
type: 'boolean',
describe: 'Whether to sort members alphabetically.',
},
includeMetadata: {
type: 'boolean',
describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
Expand Down Expand Up @@ -114,6 118,7 @@ result.then((config) => {
title: argv.title,
namespace: argv.namespace,
openApiFileName: argv.openApiFileName,
sortMembersAlphabetically: argv.sortMembersAlphabetically,
includeMetadata: argv.includeMetadata,
rootDir: argv.documentationRootDir,
onAfterProcess: config?.config?.onAfterProcess,
Expand Down
12 changes: 3 additions & 9 deletions src/model/markdown-generation-util/field-declaration-util.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 8,9 @@ export function declareField(
grouped = false,
) {
markdownFile.addBlankLine();
fields
.sort((propA, propB) => {
if (propA.name < propB.name) return -1;
if (propA.name > propB.name) return 1;
return 0;
})
.forEach((propertyModel) => {
addFieldSection(markdownFile, propertyModel, startingHeadingLevel, grouped);
});
fields.forEach((propertyModel) => {
addFieldSection(markdownFile, propertyModel, startingHeadingLevel, grouped);
});

markdownFile.addHorizontalRule();
}
Expand Down
14 changes: 4 additions & 10 deletions src/model/markdown-type-file.ts
Original file line number Diff line number Diff line change
Expand Up @@ -91,16 91,10 @@ export class MarkdownTypeFile extends MarkdownFile implements WalkerListener {

private addInnerTypes(title: string, types: Type[], addSeparator = true) {
this.addTitle(title, this.headingLevel 1);
types
.sort((typeA, typeB) => {
if (typeA.name < typeB.name) return -1;
if (typeA.name > typeB.name) return 1;
return 0;
})
.forEach((currentType) => {
const innerFile = new MarkdownTypeFile(currentType, this.headingLevel 2, undefined, true);
this.addText(innerFile._contents);
});
types.forEach((currentType) => {
const innerFile = new MarkdownTypeFile(currentType, this.headingLevel 2, undefined, true);
this.addText(innerFile._contents);
});
if (addSeparator) {
this.addHorizontalRule();
}
Expand Down
Loading

0 comments on commit c629056

Please sign in to comment.