chore(docs): add typedoc for better in-code documentation management

CONTRIBUTING.md

@@ -29,6 +29,23 @@ In order to run the demo you need to build the lib first by running `yarn lib:bu
 
 ## Maintainer notes
 
+### Documentation
+
+The documentation for components is maintained in-code using [`typedoc`](https://typedoc.org).
+
+The following categories are defined for valid use with `@category` annotation:
+
+- `Component` - should be used for Angular components (all things that have a template defined). In other words, for `*.component.ts` files
+  - `Input` - for component inputs
+  - `Output` - for component outputs (probably event emitters)
+- `Service` - should be used for `*.service.ts` files
+- `Module` - should be used for `*.module.ts` files
+- `Directive` - should be used for `*.directive.ts` files
+- `Token` - currently, all tokens are exported from `projects/ng-recaptcha/src/lib/tokens.ts` file. All documentation for `InjectionToken<T>` items should utilize this category.
+- This package exports a number of utility types and interfaces, **don't** specify a category for those.
+
+Use `/** @internal */` JSDoc annotation to exclude the method from generated documentation. In particular, this is useful for component/service constructors that have DI arguments, or for Angular component lifecycle hooks (such as `ngOnInit` and the like).
+
 ### Release
 
 In order for everything to go smooth, you'll need to check prerequisites first:
@@ -38,16 +55,17 @@ In order for everything to go smooth, you'll need to check prerequisites first:
 
 After you did that, follow the below process:
 
-- Pushed the latest changes to upstream: `git push`
+- Push the latest changes to upstream: `git push`
 
-  - use the following commit message convension when updating Angular to a newer version:
+  - use the following commit message convention when updating Angular to a newer version:
     > feat(package): add Angular N support
     >
     > BREAKING CHANGE:
     > Angular v(N-1) is no longer supported with this version. Pin `ng-recaptcha` to `vM.x.x` to retain support for a previous Angular version
 
 - Ensure that the build succeeds
 - To start with, make sure all the dependencies are up-to-date: `yarn && yarn clean`
+- Generate and commit documentation by running `yarn typedoc`
 - Then you need to prepare a release.
 
   - Export the version variable for later use by scripts: `export NGR_VERSION=<VERSION>`

docs/README.md

@@ -0,0 +1,78 @@
+ng-recaptcha
+
+# ng-recaptcha
+
+## Table of contents
+
+### Component Classes
+
+- [RecaptchaComponent](classes/RecaptchaComponent.md)
+
+### Service Classes
+
+- [ReCaptchaV3Service](classes/ReCaptchaV3Service.md)
+- [RecaptchaLoaderService](classes/RecaptchaLoaderService.md)
+
+### Module Classes
+
+- [RecaptchaFormsModule](classes/RecaptchaFormsModule.md)
+- [RecaptchaModule](classes/RecaptchaModule.md)
+- [RecaptchaV3Module](classes/RecaptchaV3Module.md)
+
+### Directive Classes
+
+- [RecaptchaValueAccessorDirective](classes/RecaptchaValueAccessorDirective.md)
+
+### Interfaces
+
+- [OnExecuteData](interfaces/OnExecuteData.md)
+- [OnExecuteErrorData](interfaces/OnExecuteErrorData.md)
+- [RecaptchaSettings](interfaces/RecaptchaSettings.md)
+
+### Type Aliases
+
+- [RecaptchaErrorParameters](README.md#recaptchaerrorparameters)
+
+### Token Variables
+
+- [RECAPTCHA_BASE_URL](README.md#recaptcha_base_url)
+- [RECAPTCHA_LANGUAGE](README.md#recaptcha_language)
+- [RECAPTCHA_NONCE](README.md#recaptcha_nonce)
+- [RECAPTCHA_SETTINGS](README.md#recaptcha_settings)
+- [RECAPTCHA_V3_SITE_KEY](README.md#recaptcha_v3_site_key)
+
+## Type Aliases
+
+### RecaptchaErrorParameters
+
+Ƭ **RecaptchaErrorParameters**: `Parameters`<`NeverUndefined`<`ReCaptchaV2.Parameters`[``"error-callback"``]\>\>
+
+## Token Variables
+
+### RECAPTCHA_BASE_URL
+
+• `Const` **RECAPTCHA_BASE_URL**: `InjectionToken`<`string`\>
+
+---
+
+### RECAPTCHA_LANGUAGE
+
+• `Const` **RECAPTCHA_LANGUAGE**: `InjectionToken`<`string`\>
+
+---
+
+### RECAPTCHA_NONCE
+
+• `Const` **RECAPTCHA_NONCE**: `InjectionToken`<`string`\>
+
+---
+
+### RECAPTCHA_SETTINGS
+
+• `Const` **RECAPTCHA_SETTINGS**: `InjectionToken`<[`RecaptchaSettings`](interfaces/RecaptchaSettings.md)\>
+
+---
+
+### RECAPTCHA_V3_SITE_KEY
+
+• `Const` **RECAPTCHA_V3_SITE_KEY**: `InjectionToken`<`string`\>

docs/classes/ReCaptchaV3Service.md

@@ -0,0 +1,85 @@
+[ng-recaptcha](../README.md) / ReCaptchaV3Service
+
+# Class: ReCaptchaV3Service
+
+The main service for working with reCAPTCHA v3 APIs.
+
+Use the `execute` method for executing a single action, and
+`onExecute` observable for listening to all actions at once.
+
+## Table of contents
+
+### Constructors
+
+- [constructor](ReCaptchaV3Service.md#constructor)
+
+### Accessors
+
+- [onExecute](ReCaptchaV3Service.md#onexecute)
+- [onExecuteError](ReCaptchaV3Service.md#onexecuteerror)
+
+### Methods
+
+- [execute](ReCaptchaV3Service.md#execute)
+
+## Constructors
+
+### constructor
+
+• **new ReCaptchaV3Service**(`zone`, `siteKey`, `platformId`, `baseUrl?`, `nonce?`, `language?`)
+
+#### Parameters
+
+| Name         | Type     |
+| :----------- | :------- |
+| `zone`       | `NgZone` |
+| `siteKey`    | `string` |
+| `platformId` | `Object` |
+| `baseUrl?`   | `string` |
+| `nonce?`     | `string` |
+| `language?`  | `string` |
+
+## Accessors
+
+### onExecute
+
+• `get` **onExecute**(): `Observable`<[`OnExecuteData`](../interfaces/OnExecuteData.md)\>
+
+#### Returns
+
+`Observable`<[`OnExecuteData`](../interfaces/OnExecuteData.md)\>
+
+---
+
+### onExecuteError
+
+• `get` **onExecuteError**(): `Observable`<[`OnExecuteErrorData`](../interfaces/OnExecuteErrorData.md)\>
+
+#### Returns
+
+`Observable`<[`OnExecuteErrorData`](../interfaces/OnExecuteErrorData.md)\>
+
+## Methods
+
+### execute
+
+▸ **execute**(`action`): `Observable`<`string`\>
+
+Executes the provided `action` with reCAPTCHA v3 API.
+Use the emitted token value for verification purposes on the backend.
+
+For more information about reCAPTCHA v3 actions and tokens refer to the official documentation at
+https://developers.google.com/recaptcha/docs/v3.
+
+#### Parameters
+
+| Name     | Type     | Description           |
+| :------- | :------- | :-------------------- |
+| `action` | `string` | the action to execute |
+
+#### Returns
+
+`Observable`<`string`\>
+
+an `Observable` that will emit the reCAPTCHA v3 string `token` value whenever ready.
+The returned `Observable` completes immediately after emitting a value.

docs/classes/RecaptchaComponent.md

@@ -0,0 +1,115 @@
+[ng-recaptcha](../README.md) / RecaptchaComponent
+
+# Class: RecaptchaComponent
+
+## Implements
+
+- `AfterViewInit`
+- `OnDestroy`
+
+## Table of contents
+
+### Properties
+
+- [badge](RecaptchaComponent.md#badge)
+- [error](RecaptchaComponent.md#error)
+- [errorMode](RecaptchaComponent.md#errormode)
+- [id](RecaptchaComponent.md#id)
+- [resolved](RecaptchaComponent.md#resolved)
+- [siteKey](RecaptchaComponent.md#sitekey)
+- [size](RecaptchaComponent.md#size)
+- [tabIndex](RecaptchaComponent.md#tabindex)
+- [theme](RecaptchaComponent.md#theme)
+- [type](RecaptchaComponent.md#type)
+
+### Methods
+
+- [execute](RecaptchaComponent.md#execute)
+- [reset](RecaptchaComponent.md#reset)
+
+## Properties
+
+### badge
+
+• **badge**: `Badge`
+
+Only applies to invisible reCAPTCHA (when [size](RecaptchaComponent.md#size) is set to `invisible`).
+
+See [`badge` parameter documentation](https://developers.google.com/recaptcha/docs/invisible#render_param) in official reCAPTCHA docs.
+
+---
+
+### error
+
+• **error**: `EventEmitter`<[]\>
+
+---
+
+### errorMode
+
+• **errorMode**: `"default"` \| `"handled"` = `"default"`
+
+---
+
+### id
+
+• **id**: `string`
+
+---
+
+### resolved
+
+• **resolved**: `EventEmitter`<`string`\>
+
+---
+
+### siteKey
+
+• **siteKey**: `string`
+
+---
+
+### size
+
+• **size**: `Size`
+
+---
+
+### tabIndex
+
+• **tabIndex**: `number`
+
+---
+
+### theme
+
+• **theme**: `Theme`
+
+---
+
+### type
+
+• **type**: `Type`
+
+## Methods
+
+### execute
+
+▸ **execute**(): `void`
+
+Executes the invisible recaptcha.
+Does nothing if component's size is not set to "invisible".
+
+#### Returns
+
+`void`
+
+---
+
+### reset
+
+▸ **reset**(): `void`
+
+#### Returns
+
+`void`

docs/classes/RecaptchaFormsModule.md

@@ -0,0 +1,15 @@
+[ng-recaptcha](../README.md) / RecaptchaFormsModule
+
+# Class: RecaptchaFormsModule
+
+## Table of contents
+
+### Constructors
+
+- [constructor](RecaptchaFormsModule.md#constructor)
+
+## Constructors
+
+### constructor
+
+• **new RecaptchaFormsModule**()

docs/classes/RecaptchaLoaderService.md

@@ -0,0 +1,35 @@
+[ng-recaptcha](../README.md) / RecaptchaLoaderService
+
+# Class: RecaptchaLoaderService
+
+## Table of contents
+
+### Constructors
+
+- [constructor](RecaptchaLoaderService.md#constructor)
+
+### Properties
+
+- [ready](RecaptchaLoaderService.md#ready)
+
+## Constructors
+
+### constructor
+
+• **new RecaptchaLoaderService**(`platformId`, `language?`, `baseUrl?`, `nonce?`, `v3SiteKey?`)
+
+#### Parameters
+
+| Name         | Type     |
+| :----------- | :------- |
+| `platformId` | `Object` |
+| `language?`  | `string` |
+| `baseUrl?`   | `string` |
+| `nonce?`     | `string` |
+| `v3SiteKey?` | `string` |
+
+## Properties
+
+### ready
+
+• **ready**: `Observable`<`ReCaptcha`\>

docs/classes/RecaptchaModule.md

@@ -0,0 +1,15 @@
+[ng-recaptcha](../README.md) / RecaptchaModule
+
+# Class: RecaptchaModule
+
+## Table of contents
+
+### Constructors
+
+- [constructor](RecaptchaModule.md#constructor)
+
+## Constructors
+
+### constructor
+
+• **new RecaptchaModule**()