docs(useGeolocation): auto-generated docs (#247)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: seungro <seungro@toss.im>
Co-authored-by: seungrodotlee <seungrodotlee@gmail.com>

Author: 3 people

.github/workflows/integration.yml

@@ -260,3 +260,63 @@ jobs:
               fi
             fi
           done
+
+  verify-exports:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check exports
+        run: |
+          IMPL_DIRS=("components" "hooks" "utils")
+          ROOT_INDEX="src/index.ts"
+          ERROR_LOG=""
+          HAS_ERROR=0
+
+          for dir in "${IMPL_DIRS[@]}"; do
+            for impl_dir in src/$dir/*/; do
+              if [ ! -d "$impl_dir" ]; then
+                continue
+              fi
+              
+              impl_name=$(basename "$impl_dir")
+              impl_index="$impl_dir/index.ts"
+              impl_file=""
+              
+              if [ -f "$impl_dir$impl_name.ts" ]; then
+                impl_file="$impl_name.ts"
+              elif [ -f "$impl_dir$impl_name.tsx" ]; then
+                impl_file="$impl_name.tsx"
+              else
+                ERROR_LOG+="❌ Implementation file not found for $impl_name\n"
+                HAS_ERROR=1
+                continue
+              fi
+              
+              if [ ! -f "$impl_index" ]; then
+                ERROR_LOG+="❌ Missing index.ts in $impl_dir\n"
+                HAS_ERROR=1
+              fi
+              
+              if ! grep -q "export.*from.*['\"]\./$impl_file['\"]" "$impl_index"; then
+                ERROR_LOG+="❌ $impl_name is not exported in $impl_index\n"
+                HAS_ERROR=1
+              fi
+              
+              relative_path="./$dir/$impl_name/index.ts"
+              if ! grep -q "export.*from.*['\"]$relative_path['\"]" "$ROOT_INDEX"; then
+                ERROR_LOG+="❌ $impl_name is not exported in root index.ts\n"
+                HAS_ERROR=1
+              fi
+            done
+          done
+
+          if [ $HAS_ERROR -eq 1 ]; then
+            echo -e "\n🚨 Export Validation Errors:\n"
+            echo -e "$ERROR_LOG"
+            echo -e "\nPlease fix the above export issues."
+            exit 1
+          else
+            echo "✅ All exports are valid!"
+          fi

.prettierignore

@@ -11,3 +11,6 @@ esm
 out
 *.d.ts
 *.tgz
+src/components/**/*.md
+src/hooks/**/*.md
+src/utils/**/*.md

.scripts/commands/generateDocs/index.ts

@@ -286,12 +286,15 @@ function getParamUl(param: Spec, nestedParams?: Spec[]) {
 }
 
 function replaceDescription(value: string) {
+  console.log(value);
   return value
     .replace(/^\s*-\s*/, '')
+    .replace(/--/g, '\n-')
     .replace(/`([^`]*)`/g, '<code>$1</code>')
     .replace(/\*\*([^**]*)\*\*/g, '<strong>$1</strong>')
     .replace(/\*([^*]*)\*/g, '<em>$1</em>')
     .replace(/_([^*]*)_/g, '<em>$1</em>')
     .replace(/\n/g, '<br />')
+    .replace(/'/g, `\\'`)
     .replace(/"/g, '&quot;');
 }

src/docs/en/contributing.md

@@ -35,6 +35,7 @@ JSDoc comments must include `@description` and `@example`, and if there are para
   - For required parameters: `@param {<type>} <parameter name> - <parameter description>`
   - For optional parameters: `@param {<type>} [<parameter name>] - <parameter description>`
   - For object parameters, both the object itself and its properties need `@param` tags.
+  - If you want to write a list under a description, use `--` instead of `-`.
 
     ```ts
     type Props = {
@@ -61,6 +62,8 @@ JSDoc comments must include `@description` and `@example`, and if there are para
      * @param {Object} [paymentMethod] - Payment information of the user.
      * @param {string} [paymentMethod.type] - Payment method.
      * @param {string} [paymentMethod.number] - Card or account number.
+     *   -- Card or account number without `-`.
+     *   -- If the number is a card number, it should be 15 or 16 digits.
      */
     ```
 
@@ -117,7 +120,7 @@ JSDoc comments must include `@description` and `@example`, and if there are para
           {
             name: 'paymentMethod.number',
             type: 'string',
-            description: 'Card or account number.',
+            description: 'Card or account number.<br/>- Card or account number without `-`.<br/>- If the number is a card number, it should be 15 or 16 digits.',
           },
         ]"
       />
@@ -127,13 +130,16 @@ JSDoc comments must include `@description` and `@example`, and if there are para
 
   - Format: `@returns {<type>} <return value description>`
   - For object or tuple return values, include descriptions for each member.
+  - If additional details are needed for each member, please use `:`.
 
     ```ts
-    type ReturnValue = [string, () => void];
+    type ReturnValue = [Object, () => void];
 
     /**
-     * @returns {[value: string, onChange: () => void]} A tuple containing:
-     * - value `string` - The value of the input.
+     * @returns {[Object, () => void]} A tuple containing:
+     * - obj `Object` - An object containing:
+     *   : label `string` - The label of the input.
+     *   : value `string` - The value of the input.
      * - onChange `() => void` - A function to update the value.
      */
     ```
@@ -147,9 +153,9 @@ JSDoc comments must include `@description` and `@example`, and if there are para
         description="A tuple containing:"
         :nested="[
           {
-            name: 'value',
-            type: 'string',
-            description: 'The value of the input.',
+            name: 'obj',
+            type: 'Object',
+            description: 'The value of the input. <br />  : label <code>string</code> - The label of the input. <br />  : value <code>string</code> - The value of the input.',
           },
           {
             name: 'onChange',

src/hooks/useGeolocation/ko/useGeolocation.md

@@ -0,0 +1,141 @@
+# useGeolocation
+
+`useGeolocation`는 사용자의 지리적 위치를 검색하고 추적하는 리액트 훅이에요. 브라우저의 `Geolocation API`를 사용하여 단회 위치 검색과 지속적인 위치 추적을 모두 지원해요.
+
+## Interface
+
+```ts
+function useGeolocation(options: GeolocationOptions): Object;
+```
+
+### 파라미터
+
+<Interface
+  name="options"
+  type="GeolocationOptions"
+  description="지리적 위치 옵션 설정이에요"
+  :nested="[
+    {
+      name: 'options.mountBehavior',
+      type: 'GeolocationMountBehaviorType',
+      required: false,
+      description:
+        '훅이 마운트 시 어떻게 동작하는지: <br />- 제공되지 않으면 자동으로 위치를 가져오지 않아요 <br />- \u0027get\u0027: 컴포넌트가 마운트될 때 위치를 자동으로 한 번 가져와요 <br />- \u0027watch\u0027: 컴포넌트가 마운트될 때 위치 변경 추적을 자동으로 시작해요',
+    },
+    {
+      name: 'options.enableHighAccuracy',
+      type: 'boolean',
+      required: false,
+      defaultValue: 'false',
+      description:
+        '만약 참이라면, 더 정확한 위치 정보를 제공해요 (배터리 소비 증가)',
+    },
+    {
+      name: 'options.maximumAge',
+      type: 'number',
+      required: false,
+      defaultValue: '0',
+      description:
+        '반환이 허용되는 캐시된 위치의 최대 나이(밀리초)예요',
+    },
+    {
+      name: 'options.timeout',
+      type: 'number',
+      required: false,
+      defaultValue: 'Infinity',
+      description:
+        '위치를 요청할 때 허용되는 최대 시간(밀리초)예요',
+    },
+  ]"
+/>
+
+### 반환 값
+
+<Interface
+  name=""
+  type="Object"
+  description="위치 데이터와 관련된 함수들을 포함하고 있어요"
+  :nested="[
+    {
+      name: 'loading',
+      type: 'boolean',
+      required: false,
+      description: '현재 위치 데이터를 가져오는 중인지 여부를 나타내요.',
+    },
+    {
+      name: 'error',
+      type: 'CustomGeoLocationError|null',
+      required: false,
+      description:
+        '오류가 발생했을 때의 오류 객체이거나 null이에요. 이 훅은 표준 Geolocation API 오류 코드(<code>1-3</code>)와 사용자 정의 코드(<code>0</code>)를 사용해요 <br />  : <code>0</code> - 이 환경에서는 지리적 위치가 지원되지 않아요 <br />  : <code>1</code> - 사용자가 지리적 위치 접근 허용을 거부했어요 <br />  : <code>2</code> - 위치를 사용할 수 없어요 <br />  : <code>3</code> - 시간 초과 - 지리적 위치 요청이 너무 오래 걸렸어요.',
+    },
+    {
+      name: 'data',
+      type: 'GeolocationData|null',
+      required: false,
+      description:
+        '위치 데이터 객체 또는 null이에요 <br />  : 위도 <code>number</code> - 십진수로 표현된 위도예요 <br />  : 경도 <code>number</code> - 십진수로 표현된 경도예요 <br />  : 정확도 <code>number</code> - 위치의 정확도(미터)예요 <br />  : 고도 <code>number|null</code> - WGS84 타원체 기준의 고도(미터)예요 <br />  : 고도 정확도 <code>number|null</code> - 고도의 정확도(미터)예요 <br />  : 방위 <code>number|null</code> - 진북에서 시계방향으로의 방위(도)예요 <br />  : 속도 <code>number|null</code> - 속도(미터/초)예요 <br />  : 타임스탬프 <code>number</code> - 위치가 검색된 시간이에요.',
+    },
+    {
+      name: 'getCurrentPosition',
+      type: 'Function',
+      required: false,
+      description: '현재 위치를 한 번 가져오는 함수에요.',
+    },
+    {
+      name: 'startTracking',
+      type: 'Function',
+      required: false,
+      description: '위치 변경 추적을 시작하는 함수에요.',
+    },
+    {
+      name: 'stopTracking',
+      type: 'Function',
+      required: false,
+      description: '위치 추적을 중지하는 함수에요.',
+    },
+    {
+      name: 'isTracking',
+      type: 'boolean',
+      required: false,
+      description: '현재 위치 추적이 활성화되어 있는지 여부를 나타내요.',
+    },
+  ]"
+/>
+
+## 예시
+
+```tsx
+// 기본 사용법
+const {
+  loading,
+  error,
+  data,
+  getCurrentPosition
+} = useGeolocation();
+
+// 컴포넌트가 마운트 될 때 자동으로 위치를 가져와요
+const {
+  loading,
+  error,
+  data
+} = useGeolocation({ mountBehavior: 'get' });
+
+// 위치 추적
+const {
+  loading,
+  error,
+  data,
+  startTracking,
+  stopTracking,
+  isTracking
+} = useGeolocation();
+
+const handleStartTracking = () => {
+  startTracking();
+};
+
+const handleStopTracking = () => {
+  stopTracking();
+};
+```