chore: integrate docgen (#327)

* init docgen * better types for docgen * generate docgen
CodetrixStudio · Nov 26, 2023 · 1e486f8 · 1e486f8
1 parent dece438
commit 1e486f8
Show file tree

Hide file tree

Showing 4 changed files with 247 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -226,6 +226,112 @@ const config: CapacitorConfig = {
 export default config;
 ```
 
+## API
+
+<docgen-index>
+
+* [`initialize(...)`](#initialize)
+* [`signIn()`](#signin)
+* [`refresh()`](#refresh)
+* [`signOut()`](#signout)
+* [Interfaces](#interfaces)
+
+</docgen-index>
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### initialize(...)
+
+```typescript
+initialize(options?: InitOptions) => void
+```
+
+Initializes the GoogleAuthPlugin, loading the gapi library and setting up the plugin.
+
+| Param         | Type                                                | Description                        |
+| ------------- | --------------------------------------------------- | ---------------------------------- |
+| **`options`** | <code><a href="#initoptions">InitOptions</a></code> | - Optional initialization options. |
+
+**Since:** 3.1.0
+
+--------------------
+
+
+### signIn()
+
+```typescript
+signIn() => Promise<User>
+```
+
+Initiates the sign-in process and returns a Promise that resolves with the user information.
+
+**Returns:** <code>Promise&lt;<a href="#user">User</a>&gt;</code>
+
+--------------------
+
+
+### refresh()
+
+```typescript
+refresh() => Promise<Authentication>
+```
+
+Refreshes the authentication token and returns a Promise that resolves with the updated authentication details.
+
+**Returns:** <code>Promise&lt;<a href="#authentication">Authentication</a>&gt;</code>
+
+--------------------
+
+
+### signOut()
+
+```typescript
+signOut() => Promise<any>
+```
+
+Signs out the user and returns a Promise.
+
+**Returns:** <code>Promise&lt;any&gt;</code>
+
+--------------------
+
+
+### Interfaces
+
+
+#### InitOptions
+
+| Prop                     | Type                  | Description                                                                                                                                      | Default            | Since |
+| ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ----- |
+| **`clientId`**           | <code>string</code>   | The app's client ID, found and created in the Google Developers Console. Common for Android or iOS. The default is defined in the configuration. |                    | 3.1.0 |
+| **`scopes`**             | <code>string[]</code> | Specifies the scopes required for accessing Google APIs The default is defined in the configuration.                                             |                    |       |
+| **`grantOfflineAccess`** | <code>boolean</code>  | Set if your application needs to refresh access tokens when the user is not present at the browser. In response use `serverAuthCode` key         | <code>false</code> | 3.1.0 |
+
+
+#### User
+
+| Prop                 | Type                                                      | Description                                                         |
+| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------- |
+| **`id`**             | <code>string</code>                                       | The unique identifier for the user.                                 |
+| **`email`**          | <code>string</code>                                       | The email address associated with the user.                         |
+| **`name`**           | <code>string</code>                                       | The user's full name.                                               |
+| **`familyName`**     | <code>string</code>                                       | The family name (last name) of the user.                            |
+| **`givenName`**      | <code>string</code>                                       | The given name (first name) of the user.                            |
+| **`imageUrl`**       | <code>string</code>                                       | The URL of the user's profile picture.                              |
+| **`serverAuthCode`** | <code>string</code>                                       | The server authentication code.                                     |
+| **`authentication`** | <code><a href="#authentication">Authentication</a></code> | The authentication details including access, refresh and ID tokens. |
+
+
+#### Authentication
+
+| Prop               | Type                | Description                                      |
+| ------------------ | ------------------- | ------------------------------------------------ |
+| **`accessToken`**  | <code>string</code> | The access token obtained during authentication. |
+| **`idToken`**      | <code>string</code> | The ID token obtained during authentication.     |
+| **`refreshToken`** | <code>string</code> | The refresh token.                               |
+
+</docgen-api>
+
 ## Migration guide
 
 #### Migrate from 3.2.x to 3.3.x

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -10,14 +10,16 @@
     "watch": "tsc --watch",
     "prepublishOnly": "npm run build",
     "prepare": "tsc",
-    "test": "echo \"no test specified\""
+    "test": "echo \"no test specified\"",
+    "docgen": "docgen --api GoogleAuthPlugin --output-readme README.md"
   },
   "author": "CodetrixStudio",
   "license": "MIT",
   "devDependencies": {
     "@capacitor/android": "^5.0.4",
     "@capacitor/cli": "^5.0.4",
     "@capacitor/core": "^5.0.4",
+    "@capacitor/docgen": "^0.2.1",
     "@capacitor/ios": "^5.0.4",
     "@ionic/prettier-config": "^2.0.0",
     "@types/gapi": "0.0.42",
@@ -64,4 +66,4 @@
     "url": "https://github.com/CodetrixStudio/CapacitorGoogleAuth/issues"
   },
   "prettier": "@ionic/prettier-config"
-}
+}
diff --git a/src/definitions.ts b/src/definitions.ts
@@ -7,34 +7,68 @@ declare module '@capacitor/cli' {
 }
 
 export interface User {
+  /**
+   * The unique identifier for the user.
+   */
   id: string;
+
+  /**
+   * The email address associated with the user.
+   */
   email: string;
+
   /**
-   * @deprecated use `name` instead
+   * The user's full name.
    */
-  displayName: string
   name: string;
+
+  /**
+   * The family name (last name) of the user.
+   */
   familyName: string;
+
+  /**
+   * The given name (first name) of the user.
+   */
   givenName: string;
+
+  /**
+   * The URL of the user's profile picture.
+   */
   imageUrl: string;
 
+  /**
+   * The server authentication code.
+   */
   serverAuthCode: string;
+
+  /**
+   * The authentication details including access, refresh and ID tokens.
+   */
   authentication: Authentication;
 }
 
 export interface Authentication {
+  /**
+   * The access token obtained during authentication.
+   */
   accessToken: string;
+
+  /**
+   * The ID token obtained during authentication.
+   */
   idToken: string;
 
   /**
-   * refreshToken only for iOS and Android
+   * The refresh token.
+   * @warning This property is applicable only for mobile platforms (iOS and Android).
    */
   refreshToken?: string;
 }
 
 export interface GoogleAuthPluginOptions {
   /**
-   * The app's client ID, found and created in the Google Developers Console.
+   * The default app's client ID, found and created in the Google Developers Console.
    * common for Android or iOS
    * @example xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
    * @since 3.1.0
@@ -54,10 +88,10 @@ export interface GoogleAuthPluginOptions {
   androidClientId?: string;
 
   /**
-   * Scopes that you might need to request to access Google APIs
+   * Specifies the default scopes required for accessing Google APIs.
    * @example ["profile", "email"]
-   * @default []
-   * @see @link https://developers.google.com/identity/protocols/oauth2/scopes
+   * @default ["email", "profile", "openid"]
+   * @see [Google OAuth2 Scopes](https://developers.google.com/identity/protocols/oauth2/scopes)
    */
   scopes?: string[];
 
@@ -75,25 +109,54 @@ export interface GoogleAuthPluginOptions {
   forceCodeForRefreshToken?: boolean;
 }
 
-export interface InitOptions extends Pick<GoogleAuthPluginOptions, 'scopes' | 'clientId'> {
+export interface InitOptions {
+  /**
+   * The app's client ID, found and created in the Google Developers Console.
+   * Common for Android or iOS.
+   * The default is defined in the configuration.
+   * @example xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
+   * @since 3.1.0
+   */
+  clientId?: string;
+
+  /**
+   * Specifies the scopes required for accessing Google APIs
+   * The default is defined in the configuration.
+   * @example ["profile", "email"]
+   * @see [Google OAuth2 Scopes](https://developers.google.com/identity/protocols/oauth2/scopes)
+   */
+  scopes?: string[];
+
   /**
    * Set if your application needs to refresh access tokens when the user is not present at the browser.
    * In response use `serverAuthCode` key
    *
    * @default false
    * @since 3.1.0
    * */
-  grantOfflineAccess: boolean;
+  grantOfflineAccess?: boolean;
 }
 
 export interface GoogleAuthPlugin {
+  /**
+   * Initializes the GoogleAuthPlugin, loading the gapi library and setting up the plugin.
+   * @param options - Optional initialization options.
+   * @since 3.1.0
+   */
+  initialize(options?: InitOptions): void;
+
+  /**
+   * Initiates the sign-in process and returns a Promise that resolves with the user information.
+   */
   signIn(): Promise<User>;
+
+  /**
+   * Refreshes the authentication token and returns a Promise that resolves with the updated authentication details.
+   */
   refresh(): Promise<Authentication>;
-  signOut(): Promise<any>;
 
   /**
-   * Init hook for load gapi and init plugin
-   * @since 3.1.0
-   * */
-  initialize(options?: Partial<InitOptions>): void;
+   * Signs out the user and returns a Promise.
+   */
+  signOut(): Promise<any>;
 }