Skip to content

Commit

Permalink
Updates for 1.0.0.3.
Browse files Browse the repository at this point in the history
  • Loading branch information
@SCWells72
SCWells72 committed Apr 12, 2023
1 parent ea05dc0 commit ab44601
Show file tree
Hide file tree
Showing 4 changed files with 330 additions and 1 deletion.
89 changes: 88 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ An API documentation generator for Salesforce Apex types and triggers and custom
* [Syntax](#syntax)
* [Installation](#installation)
* [Usage](#usage)
* [Validation](#validation)
* [License](#license)
* [Release Notes](RELEASE-NOTES.md)

Expand Down Expand Up @@ -215,7 +216,7 @@ You can specify the path to a CSS file that should be used to style the generate

If an options file is used, it should include one command-line argument per-line and can include blank lines and comments via lines starting with `#`, e.g.,

```shell
```text
apexdoc @apexdoc.opts
```

Expand All @@ -232,6 +233,92 @@ apexdoc
-nn
```

## Validation

IcApexDoc includes a highly-configurable semantic validator for ApexDoc comments and their application (or lack thereof) to the respective Apex declarations. The validator is run automatically with either the default options or those from a [validator options JSON file](#validator-options-file) specified using the `-vo/--validator-options` argument:

```text
apexdoc -p sfdx-project.json -o apexdoc -vo apexdoc_validator.json
```

where an example `apexdoc_validator.json` might contain:

```json
{
"validateMissingDocComment": true,
"validateMissingDocCommentMinimumVisibility": "GLOBAL",

"validateMissingDescriptionTag": true,

"preferredExceptionTag": "EXCEPTION",

"validateDeprecatedTagDescription": true
}
```

### Validation results

Validation results are included in the output of the `apexdoc` CLI alongside the respective file. Each reported issue includes the severity (currently `Warning` for all validation rules), file path, line number, and detailed error message, e.g.:

```text
Generating HTML files...
apexdoc/ApexDocExample_cls.html
Warning: force-app/main/default/classes/ApexDocExample.cls:40 - @param description missing for parameter 'baz' of method 'bar(String)'
Warning: force-app/main/default/classes/ApexDocExample.cls:50 - Cannot resolve symbol '#barX' for method 'fooBarBaz()'
apexdoc/ApexDocValidationTest_cls.html
Warning: force-app/main/default/classes/ApexDocValidationTest.cls:9 - @param description missing for parameter 'age' of constructor 'ApexDocValidationTest(String,Integer)'
Warning: force-app/main/default/classes/ApexDocValidationTest.cls:9 - Incorrect @param order for parameter 'age' of constructor 'ApexDocValidationTest(String,Integer)'; expected 2, actual 1
Warning: force-app/main/default/classes/ApexDocValidationTest.cls:33 - @return missing for non-void method 'getName()'
apexdoc/ShoppingListControllerTestUtil_cls.html
Warning: force-app/main/default/classes/ShoppingListControllerTestUtil.cls:14 - @return description missing for method 'createNewObject()'
Warning: force-app/main/default/classes/ShoppingListControllerTestUtil.cls:27 - @return description missing for method 'createExistingObject()'
```

### Validator options file

The following properties can be configured in the validator options JSON file:

| Property | Description |
|--------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `validateMissingDocComment` | If enabled, report declarations that meet or exceed the minimum visibility for ApexDoc generation that do not have a documentation comment. Disabled by default. |
| `validateMissingDocCommentMinimumVisibility` | The minimum visibility for which `validateMissingDocComment` should apply as one of `PRIVATE`, `PROTECTED`, `PUBLIC`, or `GLOBAL`. The default is `PROTECTED`. |
| `validateMissingDocCommentIgnoreDeprecated` | If enabled and `validateMissingDocComment` is also enabled, `@Deprecated` declarations that would otherwise be flagged by `validateMissingDocComment` are ignored. Enabled by default. |
| `validateMissingDocCommentIgnoreInherited` | If enabled and `validateMissingDocComment` is also enabled, declarations that would otherwise be flagged by `validateMissingDocComment` but which inherit a documentation comment from a base declaration are ignored. Enabled by default. |
| `validateMissingDocCommentIgnoreExtendsSystemType` | If enabled and `validateMissingDocComment` is also enabled, declarations that would otherwise be flagged by `validateMissingDocComment` but which extend a standard/system Apex type are ignored. Disabled by default. |
| `validateMissingDocCommentIgnoreOverridesSystemMethod` | If enabled and `validateMissingDocComment` is also enabled, declarations that would otherwise be flagged by `validateMissingDocComment` but which implement/override a method from a standard/system Apex type are ignored. Enabled by default. |
| `validateUnresolvableAtLink` | If enabled, unresolvable declaration references in `{@link ...}` macros are flagged. Enabled by default. |
| `validateUnresolvableTypeReference` | If enabled, unresolvable declaration references in `<<...>>` macros are flagged. Enabled by default. |
| `validateMissingDescriptionTag` | If enabled, description text that is not explicitly designated with the `@description` tag are flagged. Disabled by default. |
| `validateMissingParamTag` | If enabled, formal parameters which do not have a corresponding `@param` tag in the parent method or constructor's documentation comment are flagged. Enabled by default. |
| `validateMissingParamTagName` | If enabled, `@param` tags which do not specify a formal parameter name are flagged. Enabled by default. |
| `validateMissingParamTagDescription` | If enabled, `@param` tags which do not provide a description are flagged. Enabled by default. |
| `validateIncorrectlyOrderedParamTag` | If enabled, `@param` tags which are not listed in the exact same order as their respective formal parameters are flagged. Enabled by default. |
| `validateUnresolvableParamTag` | If enabled, `@param` tags which specify a formal parameter name that does not correspond to an actual formal parameter of the documented method or constructor are flagged. Enabled by default. |
| `validateMisattributedParamTag` | If enabled, `@param` tags used in the documentation comment for any declaration type that does not accept formal parameters are flagged. Enabled by default. |
| `validateMissingReturnTag` | If enabled, documentation comments for methods that specify a non-void return type but do not include an `@return/s` tag are flagged. Enabled by default. |
| `validateExtraneousReturnTag` | If enabled, documentation comments for methods that specify a void return type but include an `@return/s` tag are flagged. Enabled by default. |
| `validateMissingReturnTagDescription` | If enabled, `@return/s` tags which do not provide a description are flagged. Enabled by default. |
| `validateMisattributedReturnTag` | If enabled, `@return/s` tags used in the documentation comment for any declaration type that does have an explicit return type (including constructors) are flagged. Enabled by default. |
| `validateReturnsTagUsage` | If enabled, usages of the non-standard `@returns` tag are flagged. It is recommended that the standard `@return` tag be used instead. Enabled by default. |
| `validateMissingExceptionTagTypeName` | If enabled, `@throws/@exception` tags which do not specify an exception type name are flagged. Enabled by default. |
| `validateUnresolvableExceptionTagTypeName` | If enabled, `@throws/@exception` tags which specify an exception type name that cannot be resolved are flagged. Enabled by default. |
| `validateMissingExceptionTagDescription` | If enabled, `@throws/@exception` tags which do not provide a description for the thrown exception are flagged. Enabled by default. |
| `validateMisattributedExceptionTag` | If enabled, `@throws/@exception` tags used in the documentation comment for any declaration type that cannot throw an exception are flagged. Enabled by default. |
| `preferredExceptionTag` | The preferred tag for documenting thrown exceptions, either `THROWS` or `EXCEPTION`. The non-preferred tag is flagged when found. The default is `THROWS`. |
| `validateMissingSeeTagTypeMemberName` | If enabled, `@see` tags which do not specify a target are flagged. Enabled by default. |
| `validateUnresolvableSeeTagTypeMemberName` | If enabled, `@see` tags which specify an unresolvable target are flagged. Enabled by default. |
| `validateMissingSeeTagDescription` | If enabled, `@see` tags which do not provide a description for the referenced target are flagged. Disabled by default. |
| `validateAuthorTagValue` | If enabled, `@author` tags which do not specify a value are flagged. Enabled by default. |
| `validateGroupTagValue` | If enabled, `@group` tags which do not specify a group name are flagged. Enabled by default. |
| `validateDateTagValue` | If enabled, `@date` tags which do not specify a value are flagged. Enabled by default. |
| `validateSinceTagValue` | If enabled, `@since` tags which do not specify a value are flagged. Enabled by default. |
| `validateExampleTagValue` | If enabled, `@example` tags which do not specify a value are flagged. Enabled by default. |
| `validateDeprecatedTagDescription` | If enabled, `@deprecated` tags which do not provide a description are flagged. Disabled by default. |

Note that it is only necessary to include options _for which values are different from their defaults_ in an options file. The default values for all unspecified options will be used automatically.

A [JSON schema](validator/apexdoc_validator.schema.json) is available and can be registered with most IDEs to provide code completion and validation for these options files. A comprehensive [example configuration file](validator/apexdoc_validator_example.json), is also available for reference, but as stated previously, _only customized properties_ need to be included in the options file.

## License

IcApexDoc is 100% free to use under the [**Apache 2.0 License**](https://www.apache.org/licenses/LICENSE-2.0). Note that while portions of IcApexDoc have been derived from [**Illuminated Cloud 2**](https://www.illuminatedcloud.com/), that product&mdash;and its predecessor [**Illuminated Cloud 1**](https://www.illuminatedcloud.com/purchase/illuminated-cloud-1)&mdash;are **commercial products** offered under their own legal [**Terms and Conditions**](https://www.illuminatedcloud.com/purchase/terms-and-conditions). Access to or usage of IcApexDoc does not **in any way** entitle the user to a license for either Illuminated Cloud 2 or Illuminated Cloud 1.
5 changes: 5 additions & 0 deletions RELEASE-NOTES.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,13 @@
# Release Notes

* [1.0.0.3](#1003)
* [1.0.0.2](#1002)
* [1.0.0.1](#1001)

## [1.0.0.3](https://github.com/SCWells72/IcApexDoc/releases/tag/1.0.0.3)

* [Issue 3](https://github.com/SCWells72/IcApexDoc/issues/3) - IcApexDoc now performs [full semantic validation](README.md#validation) of ApexDoc, reporting issues, omissions, etc., about ApexDoc comments and their respective Apex declarations. Validation rules are fully configurable via a [JSON options file](README.md#validator-options-file).

## [1.0.0.2](https://github.com/SCWells72/IcApexDoc/releases/tag/1.0.0.2)

* [Issue 4](https://github.com/SCWells72/IcApexDoc/issues/4) - IcApexDoc can now read its command-line options from a file by invoking it as `apexdoc @<file>`. Command-line options should be specified exactly one per-line, and blank lines and comments (designated by `#` in the first column) are allowed in the file.
Expand Down
Loading

0 comments on commit ab44601

Please sign in to comment.