From 379ffe6d13ea4eb2769ad0e749d41c8919b5a435 Mon Sep 17 00:00:00 2001
From: JIN <o3ouuu@inu.ac.kr>
Date: Thu, 7 Nov 2024 17:56:28 +0900
Subject: [PATCH] =?UTF-8?q?=F0=9F=92=A1=20comment:=20service=20=EB=A1=9C?=
 =?UTF-8?q?=EC=A7=81=20=ED=95=A8=EC=88=98=EB=B3=84=20=EC=A3=BC=EC=84=9D=20?=
 =?UTF-8?q?=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 BE/src/stock/topfive/stock.topfive.service.ts | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/BE/src/stock/topfive/stock.topfive.service.ts b/BE/src/stock/topfive/stock.topfive.service.ts
index 48a7dff9..d8da1643 100644
--- a/BE/src/stock/topfive/stock.topfive.service.ts
+++ b/BE/src/stock/topfive/stock.topfive.service.ts
@@ -20,6 +20,13 @@ export class StockTopfiveService {
     private readonly koreaInvestmentService: KoreaInvestmentService,
   ) {}
 
+  /**
+   * @private 한국투자 Open API - [국내주식] 순위 분석 - 국내주식 등락률 순위 호출 함수
+   * @param {StockRankingQueryParameterDto} queryParams - API 요청 시 필요한 쿼리 파라미터 DTO
+   * @returns - 국내주식 등락률 데이터
+   *
+   * @author uuuo3o
+   */
   private async requestApi(queryParams: StockRankingQueryParameterDto) {
     try {
       const accessToken = await this.koreaInvestmentService.getAccessToken();
@@ -45,6 +52,13 @@ export class StockTopfiveService {
     }
   }
 
+  /**
+   * 국내주식 등락률 데이터 중 필요한 시장 종류 데이터를 반환하는 함수
+   * @param {MarketType} marketType - 시장 종류(ALL, KOSPI, KOSDAQ, KOSPI200)
+   * @returns - 상승율순, 하락율순 배열 데이터가 포함된 객체
+   *
+   * @author uuuo3o
+   */
   async getMarketRanking(marketType: MarketType) {
     try {
       const queryParams = new StockRankingQueryParameterDto();
@@ -94,6 +108,13 @@ export class StockTopfiveService {
     }
   }
 
+  /**
+   * @private API에서 받은 국내주식 등락률 데이터를 필요한 정보로 정제하는 함수
+   * @param {StockApiOutputData[]} stocks - API 응답에서 받은 원시 데이터 배열
+   * @returns - 필요한 정보만 추출한 데이터 배열
+   *
+   * @author uuuo3o
+   */
   private formatStockData(stocks: StockApiOutputData[]) {
     return stocks.slice(0, 5).map((stock) => {
       const stockData = new StockRankingDataDto();
@@ -107,6 +128,13 @@ export class StockTopfiveService {
     });
   }
 
+  /**
+   * @private 주식 순위 API 요청을 위한 쿼리 파라미터 객체 생성 함수
+   * @param {StockRankingQueryParameterDto} params - API 요청에 필요한 쿼리 파라미터 DTO
+   * @returns - API 요청에 필요한 쿼리 파라미터 객체
+   *
+   * @author uuuo3o
+   */
   private getStockRankingParams(params: StockRankingQueryParameterDto) {
     return {
       fid_rsfl_rate2: '',