Skip to content

Commit bda648e

Browse files
jcesarmobilejcesarmobile
authored
docs: Use docgen to generate plugin docs from type definitions (capacitor-community#78)
1 parent 606ccb4 commit bda648e

File tree

5 files changed

+329
-62
lines changed

5 files changed

+329
-62
lines changed

Diff for: ‎README.md

+199-54
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@ Capacitor community plugin for speech recognition.
44

55
## Maintainers
66

7-
| Maintainer | GitHub | Social | Sponsoring Company |
8-
| --------------- | ------------------------------------------- | ------------------------------------------------ | ------------------ |
9-
| Priyank Patel | [priyankpat](https://github.com/priyankpat) | [@priyankpat\_](https://twitter.com/priyankpat_) | Ionic |
10-
| Matteo Padovano | [mrbatista](https://github.com/mrbatista) | [@mrba7ista](https://twitter.com/mrba7ista) | |
7+
| Maintainer | GitHub | Social |
8+
| --------------- | ------------------------------------------- | ------------------------------------------------ |
9+
| Priyank Patel | [priyankpat](https://github.com/priyankpat) | [@priyankpat\_](https://twitter.com/priyankpat_) |
10+
| Matteo Padovano | [mrbatista](https://github.com/mrbatista) | [@mrba7ista](https://twitter.com/mrba7ista) |
1111

1212
Maintenance Status: Actively Maintained
1313

@@ -42,43 +42,32 @@ iOS requires the following usage descriptions be added and filled out for your a
4242

4343
No further action required.
4444

45-
## Configuration
45+
## Supported methods
4646

47-
No configuration required for this plugin
47+
<docgen-index>
4848

49-
## Supported methods
49+
- [`available()`](#available)
50+
- [`start(...)`](#start)
51+
- [`stop()`](#stop)
52+
- [`getSupportedLanguages()`](#getsupportedlanguages)
53+
- [`hasPermission()`](#haspermission)
54+
- [`requestPermission()`](#requestpermission)
55+
- [`checkPermissions()`](#checkpermissions)
56+
- [`requestPermissions()`](#requestpermissions)
57+
- [`addListener('partialResults', ...)`](#addlistenerpartialresults)
58+
- [`removeAllListeners()`](#removealllisteners)
59+
- [Interfaces](#interfaces)
60+
- [Type Aliases](#type-aliases)
5061

51-
| Name | Android | iOS | Web |
52-
| :-------------------- | :------ | :-- | :-- |
53-
| available | ✅ | ✅ | ❌ |
54-
| start | ✅ | ✅ | ❌ |
55-
| stop | ✅ | ✅ | ❌ |
56-
| getSupportedLanguages | ✅ | ✅ | ❌ |
57-
| hasPermission | ✅ | ✅ | ❌ |
58-
| requestPermission | ✅ | ✅ | ❌ |
62+
</docgen-index>
5963

60-
## Usage
64+
## Example
6165

6266
```typescript
6367
import { SpeechRecognition } from "@capacitor-community/speech-recognition";
6468

65-
/**
66-
* This method will check if speech recognition feature is available on the device.
67-
* @param none
68-
* @returns available - boolean true/false for availability
69-
*/
7069
SpeechRecognition.available();
7170

72-
/**
73-
* This method will start to listen for utterance.
74-
* @param language - language key returned from getSupportedLanguages()
75-
* maxResults - maximum number of results to return (5 is max)
76-
* prompt - prompt message to display on popup (Android only)
77-
* partialResults - return partial results if found
78-
* popup - display popup window when listening for utterance (Android only)
79-
* If partialResults is true, the function respond directly without result and event `partialResults` will be emit for each partial result, until stopped.
80-
* @returns void
81-
*/
8271
SpeechRecognition.start({
8372
language: "en-US",
8473
maxResults: 2,
@@ -94,34 +83,190 @@ SpeechRecognition.addListener("partialResults", (data: any) => {
9483
// stop listening partial results
9584
SpeechRecognition.removeAllListeners();
9685

97-
/**
98-
* This method will stop listening for utterance
99-
* @param none
100-
* @returns void
101-
*/
10286
SpeechRecognition.stop();
10387

104-
/**
105-
* This method will return list of languages supported by the speech recognizer.
106-
*
107-
* It's not available on Android 13 and newer.
108-
*
109-
* @param none
110-
* @returns languages - array string of languages
111-
*/
11288
SpeechRecognition.getSupportedLanguages();
11389

114-
/**
115-
* This method will check for audio permissions.
116-
* @param none
117-
* @returns permission - boolean true/false if permissions are granted
118-
*/
90+
SpeechRecognition.checkPermissions();
91+
92+
SpeechRecognition.requestPermissions();
93+
11994
SpeechRecognition.hasPermission();
12095

121-
/**
122-
* This method will prompt the user for audio permission.
123-
* @param none
124-
* @returns void
125-
*/
12696
SpeechRecognition.requestPermission();
12797
```
98+
99+
<docgen-api>
100+
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
101+
102+
### available()
103+
104+
```typescript
105+
available() => Promise<{ available: boolean; }>
106+
```
107+
108+
This method will check if speech recognition feature is available on the device.
109+
110+
**Returns:** <code>Promise&lt;{ available: boolean; }&gt;</code>
111+
112+
---
113+
114+
### start(...)
115+
116+
```typescript
117+
start(options?: UtteranceOptions) => Promise<{ matches?: string[]; }>
118+
```
119+
120+
This method will start to listen for utterance.
121+
122+
if `partialResults` is `true`, the function respond directly without result and
123+
event `partialResults` will be emit for each partial result, until stopped.
124+
125+
| Param | Type |
126+
| ------------- | ------------------------------------------------------------- |
127+
| **`options`** | <code><a href="#utteranceoptions">UtteranceOptions</a></code> |
128+
129+
**Returns:** <code>Promise&lt;{ matches?: string[]; }&gt;</code>
130+
131+
---
132+
133+
### stop()
134+
135+
```typescript
136+
stop() => Promise<void>
137+
```
138+
139+
This method will stop listening for utterance
140+
141+
---
142+
143+
### getSupportedLanguages()
144+
145+
```typescript
146+
getSupportedLanguages() => Promise<{ languages: any[]; }>
147+
```
148+
149+
This method will return list of languages supported by the speech recognizer.
150+
151+
It's not available on Android 13 and newer.
152+
153+
**Returns:** <code>Promise&lt;{ languages: any[]; }&gt;</code>
154+
155+
---
156+
157+
### hasPermission()
158+
159+
```typescript
160+
hasPermission() => Promise<{ permission: boolean; }>
161+
```
162+
163+
This method will check for audio permissions.
164+
165+
**Returns:** <code>Promise&lt;{ permission: boolean; }&gt;</code>
166+
167+
---
168+
169+
### requestPermission()
170+
171+
```typescript
172+
requestPermission() => Promise<void>
173+
```
174+
175+
This method will prompt the user for audio permission.
176+
177+
---
178+
179+
### checkPermissions()
180+
181+
```typescript
182+
checkPermissions() => Promise<PermissionStatus>
183+
```
184+
185+
Check the speech recognition permission.
186+
187+
**Returns:** <code>Promise&lt;<a href="#permissionstatus">PermissionStatus</a>&gt;</code>
188+
189+
**Since:** 5.0.0
190+
191+
---
192+
193+
### requestPermissions()
194+
195+
```typescript
196+
requestPermissions() => Promise<PermissionStatus>
197+
```
198+
199+
Request the speech recognition permission.
200+
201+
**Returns:** <code>Promise&lt;<a href="#permissionstatus">PermissionStatus</a>&gt;</code>
202+
203+
**Since:** 5.0.0
204+
205+
---
206+
207+
### addListener('partialResults', ...)
208+
209+
```typescript
210+
addListener(eventName: "partialResults", listenerFunc: (data: { matches: string[]; }) => void) => Promise<PluginListenerHandle> & PluginListenerHandle
211+
```
212+
213+
Called when partialResults set to true and result received.
214+
215+
On Android it doesn't work if popup is true.
216+
217+
Provides partial result.
218+
219+
| Param | Type |
220+
| ------------------ | ------------------------------------------------------ |
221+
| **`eventName`** | <code>'partialResults'</code> |
222+
| **`listenerFunc`** | <code>(data: { matches: string[]; }) =&gt; void</code> |
223+
224+
**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt; & <a href="#pluginlistenerhandle">PluginListenerHandle</a></code>
225+
226+
**Since:** 2.0.2
227+
228+
---
229+
230+
### removeAllListeners()
231+
232+
```typescript
233+
removeAllListeners() => Promise<void>
234+
```
235+
236+
Remove all the listeners that are attached to this plugin.
237+
238+
**Since:** 4.0.0
239+
240+
---
241+
242+
### Interfaces
243+
244+
#### UtteranceOptions
245+
246+
| Prop | Type | Description |
247+
| -------------------- | -------------------- | ---------------------------------------------------------------- |
248+
| **`language`** | <code>string</code> | key returned from `getSupportedLanguages()` |
249+
| **`maxResults`** | <code>number</code> | maximum number of results to return (5 is max) |
250+
| **`prompt`** | <code>string</code> | prompt message to display on popup (Android only) |
251+
| **`popup`** | <code>boolean</code> | display popup window when listening for utterance (Android only) |
252+
| **`partialResults`** | <code>boolean</code> | return partial results if found |
253+
254+
#### PermissionStatus
255+
256+
| Prop | Type | Description | Since |
257+
| ----------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
258+
| **`speechRecognition`** | <code><a href="#permissionstate">PermissionState</a></code> | Permission state for speechRecognition alias. On Android it requests/checks RECORD_AUDIO permission On iOS it requests/checks the speech recognition and microphone permissions. | 5.0.0 |
259+
260+
#### PluginListenerHandle
261+
262+
| Prop | Type |
263+
| ------------ | ----------------------------------------- |
264+
| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
265+
266+
### Type Aliases
267+
268+
#### PermissionState
269+
270+
<code>'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'</code>
271+
272+
</docgen-api>

0 commit comments

Comments
 (0)