From 13a380023f001d97792a56e03a80a1eab7f88fa1 Mon Sep 17 00:00:00 2001
From: Dmitry <58977309+Mon4ik@users.noreply.github.com>
Date: Tue, 24 Sep 2024 08:39:49 +0300
Subject: [PATCH] docs: updated/added comments

---
 src/oauth/index.ts       |  2 +-
 src/yandex/Capability.ts |  5 +++++
 src/yandex/Device.ts     |  6 +++++-
 src/yandex/api.ts        | 21 +++++++++++++++++----
 src/yandex/controller.ts | 12 +++++++-----
 5 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/src/oauth/index.ts b/src/oauth/index.ts
index 4c7b40c..95f3486 100644
--- a/src/oauth/index.ts
+++ b/src/oauth/index.ts
@@ -1,7 +1,7 @@
 // oAuth server
 
 import express, { Express } from "express";
-import ip from "ip"
+
 import { Server } from "net";
 import { Globals } from "../Globals.js";
 import { YandexAPI } from "../yandex/api.js";
diff --git a/src/yandex/Capability.ts b/src/yandex/Capability.ts
index b297eb7..b37f7da 100644
--- a/src/yandex/Capability.ts
+++ b/src/yandex/Capability.ts
@@ -2,6 +2,11 @@ import _ from "lodash"
 
 import type { YandexCapability } from "../types.js";
 
+/**
+ * Yandex Capability, property of a `Device`, that describes its capabilities.
+ *
+ * @see https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/capability-types
+ */
 export class Capability {
     private _capability: YandexCapability.Any
     private _pendingActions: Map<string, Record<string, any>>
diff --git a/src/yandex/Device.ts b/src/yandex/Device.ts
index 63b66db..a42fa2d 100644
--- a/src/yandex/Device.ts
+++ b/src/yandex/Device.ts
@@ -8,6 +8,10 @@ import chalk from "chalk";
 import * as hap from "hap-nodejs";
 import _ from "lodash";
 
+/**
+ * Class, representing yandex Device, that also
+ * syncs with Homekit
+ */
 export class Device {
     private readonly _accessory: Accessory
     private _service: Service
@@ -34,6 +38,7 @@ export class Device {
     }
 
     // Basic YandexAPI fields
+
     get id() {
         return this._initialDevice.id
     }
@@ -123,6 +128,5 @@ export class Device {
         await this.initCapabilities()
 
         this._accessory.addService(this._service)
-        // service.getCharacteristic()
     }
 }
diff --git a/src/yandex/api.ts b/src/yandex/api.ts
index cf0c568..49a5cd1 100644
--- a/src/yandex/api.ts
+++ b/src/yandex/api.ts
@@ -4,8 +4,11 @@ import chalk from "chalk";
 
 import { Globals } from "../Globals.js";
 
-import type { GetDevicesResponse, YandexResponse } from "../types.js";
+import type { GetDevicesResponse, YandexDevice, YandexResponse } from "../types.js";
 
+/**
+ * Yandex API
+ */
 export class YandexAPI {
     public get token() {
         return Globals.getOauth().accessToken
@@ -30,7 +33,10 @@ export class YandexAPI {
 
     // IOT associated things //
 
-    async getDevices() {
+    /**
+     * Request yandex devices
+     */
+    async getDevices(): Promise<YandexDevice[]> {
         try {
             const resp = await this.request("/user/info", {})
 
@@ -43,6 +49,9 @@ export class YandexAPI {
         }
     }
 
+    /**
+     * Apply actions to Yandex
+     */
     async applyActions(devices: any): Promise<true> {
         try {
             await this.request("/devices/actions", {
@@ -60,6 +69,9 @@ export class YandexAPI {
 
     // Token associated things //
 
+    /**
+     * Refresh Yandex's token
+     */
     async refreshToken() {
         const refreshToken = Globals.getOauth().refreshToken
         const client = Globals.getConfig().client
@@ -101,6 +113,9 @@ export class YandexAPI {
         })
     }
 
+    /**
+     * Exchange code to token
+     */
     async exchangeToken(code: string) {
         const client = Globals.getConfig().client
         const authHeader = Buffer.from(`${client.id}:${client.secret}`).toString("base64")
@@ -133,6 +148,4 @@ export class YandexAPI {
             expiresAt: Date.now() + resp.data.expires_in * 1000
         })
     }
-
-
 }
diff --git a/src/yandex/controller.ts b/src/yandex/controller.ts
index 80f240a..6e068d5 100644
--- a/src/yandex/controller.ts
+++ b/src/yandex/controller.ts
@@ -7,9 +7,9 @@ import { YandexAPI } from "./api.js";
 import { YandexDevice } from "../types.js";
 
 /*
- * Controller for:
- *  - Syncing devices
- *  - Managing token
+ * Yandex Controller that:
+ *  - Sync devices
+ *  - Manage token
  */
 export class YandexController {
     private readonly bridge: hap.Bridge
@@ -97,10 +97,12 @@ export class YandexController {
         await this.yandexAPI.refreshToken()
 
         // update interval
-        this.refreshAt = Globals.getOauth().expiresAt - 15_000 // expiresAt - 15 secs, becoz network speed
+        this.refreshAt = Globals.getOauth().expiresAt - 15_000 // expiresAt - 15 secs
     }
 
-    /* Verify existing token, and(or) create new */
+    /**
+     * Verify existing token, and(or) create new
+     */
     private async tokenVerify() {
         const oauth = Globals.getOauth()