GitHub Copilot - 가장 대중적인 선택

특징:
• VS Code, JetBrains IDE 등 주요 에디터 지원
• 실시간으로 주석 제안
• 코드 작성 중 자동 완성처럼 작동
• 월 $10 (학생/오픈소스 기여자 무료)

사용법:
함수 위에 /**를 입력하고 엔터를 치면, Copilot이 자동으로 JSDoc 형식의 주석을 제안합니다. Tab 키로 수락하면 끝! 정말 간단하죠? 😎

// Copilot이 자동 생성한 주석
/**
 * 사용자의 나이를 계산합니다
 * @param {string} birthDate - 생년월일 (YYYY-MM-DD 형식)
 * @returns {number} 만 나이
 * @throws {Error} 잘못된 날짜 형식일 경우
 */
function calculateAge(birthDate) {
  const today = new Date();
  const birth = new Date(birthDate);
  let age = today.getFullYear() - birth.getFullYear();
  const monthDiff = today.getMonth() - birth.getMonth();
  
  if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birth.getDate())) {
    age--;
  }
  
  return age;
}

Tabnine - 프라이버시 중시형

특징:
• 로컬 모델 옵션 제공 (코드가 외부로 나가지 않음)
• 팀 학습 기능 (팀의 코딩 스타일 학습)
• 다양한 언어 지원 (30개 이상)
• 무료 버전도 꽤 강력함

장점:
보안이 중요한 기업 환경에서 특히 유용합니다. 민감한 코드를 외부 서버로 보내지 않고도 AI의 도움을 받을 수 있거든요! 🔒

Mintlify - 문서화 특화

특징:
• 주석뿐만 아니라 전체 문서 생성
• 웹 기반 문서 사이트 자동 생성
• README, API 문서 자동화
• VS Code 확장 프로그램 제공

사용 시나리오:
오픈소스 프로젝트나 API를 개발할 때 특히 좋아요. 코드에서 자동으로 문서를 추출해서 깔끔한 웹사이트로 만들어줍니다. 📖

Kite (현재 중단됨, 하지만 배울 점이 많음)

역사적 의의:
Kite는 2022년에 서비스를 종료했지만, AI 주석 자동화의 선구자였어요. 무료로 강력한 기능을 제공했고, 많은 개발자들이 사랑했죠.

교훈:
AI 도구를 선택할 때는 지속 가능성도 고려해야 합니다. 큰 회사가 지원하거나, 오픈소스이거나, 명확한 수익 모델이 있는 도구를 선택하는 게 안전해요. 💡

ChatGPT/Claude API 직접 활용

DIY 접근법:
개발자라면 직접 스크립트를 만들어서 사용할 수도 있어요! OpenAI API나 Anthropic API를 사용하면 됩니다.

장점:
• 완전한 커스터마이징 가능
• 팀의 주석 스타일에 맞게 조정
• 다른 자동화 워크플로우와 통합 가능

단점:
• 초기 설정에 시간 필요
• API 비용 발생 (하지만 생각보다 저렴함)

import openai
import os

def generate_docstring(code):
    """
    주어진 코드에 대한 docstring을 생성합니다
    """
    openai.api_key = os.getenv("OPENAI_API_KEY")
    
    prompt = f"""
    다음 Python 함수에 대한 상세한 docstring을 작성해주세요.
    Google 스타일을 따르고, 한국어로 작성해주세요.
    
    코드:
    {code}
    
    Docstring:
    """
    
    response = openai.ChatCompletion.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": "당신은 Python 문서화 전문가입니다."},
            {"role": "user", "content": prompt}
        ],
        temperature=0.3
    )
    
    return response.choices[0].message.content

# 사용 예시
code_sample = """
def merge_sort(arr):
    if len(arr) <= 1:
        return arr
    mid = len(arr) // 2
    left = merge_sort(arr[:mid])
    right = merge_sort(arr[mid:])
    return merge(left, right)
"""

docstring = generate_docstring(code_sample)
print(docstring)

프로젝트 설정

# Python 환경
pip install openai python-dotenv ast-parser

# Node.js 환경
npm install openai dotenv @babel/parser

API 키 설정:

# .env 파일
OPENAI_API_KEY=your_api_key_here
MODEL=gpt-4

코드 파싱 모듈

먼저 코드를 분석해서 함수들을 추출해야 해요:

import ast
import os
from typing import List, Dict

class CodeParser:
    """코드를 파싱하여 함수 정보를 추출하는 클래스"""
    
    def __init__(self, file_path: str):
        self.file_path = file_path
        with open(file_path, 'r', encoding='utf-8') as f:
            self.source = f.read()
        self.tree = ast.parse(self.source)
    
    def extract_functions(self) -> List[Dict]:
        """
        모든 함수 정의를 추출합니다
        
        Returns:
            함수 정보 딕셔너리 리스트
            각 딕셔너리는 name, args, body, lineno를 포함
        """
        functions = []
        
        for node in ast.walk(self.tree):
            if isinstance(node, ast.FunctionDef):
                func_info = {
                    'name': node.name,
                    'args': [arg.arg for arg in node.args.args],
                    'body': ast.get_source_segment(self.source, node),
                    'lineno': node.lineno,
                    'has_docstring': ast.get_docstring(node) is not None
                }
                functions.append(func_info)
        
        return functions
    
    def get_function_source(self, func_name: str) -> str:
        """특정 함수의 소스 코드를 반환합니다"""
        for node in ast.walk(self.tree):
            if isinstance(node, ast.FunctionDef) and node.name == func_name:
                return ast.get_source_segment(self.source, node)
        return None

AI 주석 생성 모듈

import openai
from dotenv import load_dotenv

load_dotenv()

class AIDocGenerator:
    """AI를 사용하여 코드 주석을 생성하는 클래스"""
    
    def __init__(self, model: str = "gpt-4"):
        self.model = model
        openai.api_key = os.getenv("OPENAI_API_KEY")
    
    def generate_docstring(
        self, 
        function_code: str, 
        style: str = "google",
        language: str = "ko"
    ) -> str:
        """
        함수 코드에 대한 docstring을 생성합니다
        
        Args:
            function_code: 분석할 함수의 소스 코드
            style: docstring 스타일 (google, numpy, sphinx)
            language: 주석 언어 (ko, en, ja)
        
        Returns:
            생성된 docstring
        """
        
        style_guides = {
            "google": "Google Python Style Guide",
            "numpy": "NumPy Documentation Style",
            "sphinx": "Sphinx Documentation Style"
        }
        
        lang_names = {
            "ko": "한국어",
            "en": "영어",
            "ja": "일본어"
        }
        
        prompt = f"""
다음 Python 함수에 대한 상세한 docstring을 작성해주세요.

스타일: {style_guides.get(style, 'Google Python Style Guide')}
언어: {lang_names.get(language, '한국어')}

요구사항:
1. 함수의 목적을 명확히 설명
2. 모든 파라미터 설명
3. 반환값 설명
4. 발생 가능한 예외 설명
5. 필요시 사용 예시 포함

함수 코드:
```python
{function_code}
```

Docstring만 출력해주세요 (코드는 제외):
"""
        
        try:
            response = openai.ChatCompletion.create(
                model=self.model,
                messages=[
                    {
                        "role": "system", 
                        "content": "당신은 Python 문서화 전문가입니다. 명확하고 상세한 docstring을 작성합니다."
                    },
                    {"role": "user", "content": prompt}
                ],
                temperature=0.3,
                max_tokens=1000
            )
            
            return response.choices[0].message.content.strip()
        
        except Exception as e:
            print(f"AI 생성 중 오류 발생: {e}")
            return None
    
    def generate_inline_comments(self, function_code: str) -> str:
        """
        함수 내부에 인라인 주석을 추가합니다
        
        Args:
            function_code: 주석을 추가할 함수 코드
        
        Returns:
            주석이 추가된 코드
        """
        prompt = f"""
다음 Python 함수의 복잡한 부분에 인라인 주석을 추가해주세요.
주석은 한국어로 작성하고, 코드의 의도를 명확히 설명해야 합니다.

원본 코드:
```python
{function_code}
```

주석이 추가된 전체 코드를 출력해주세요:
"""
        
        try:
            response = openai.ChatCompletion.create(
                model=self.model,
                messages=[
                    {
                        "role": "system",
                        "content": "당신은 코드 가독성 전문가입니다."
                    },
                    {"role": "user", "content": prompt}
                ],
                temperature=0.3,
                max_tokens=1500
            )
            
            return response.choices[0].message.content.strip()
        
        except Exception as e:
            print(f"인라인 주석 생성 중 오류: {e}")
            return function_code

통합 및 실행

import sys
from pathlib import Path

class AutoDocumenter:
    """코드 파일을 자동으로 문서화하는 메인 클래스"""
    
    def __init__(self, style: str = "google", language: str = "ko"):
        self.parser = None
        self.generator = AIDocGenerator()
        self.style = style
        self.language = language
    
    def process_file(self, file_path: str, output_path: str = None):
        """
        파일을 처리하여 주석을 추가합니다
        
        Args:
            file_path: 처리할 Python 파일 경로
            output_path: 출력 파일 경로 (None이면 원본 수정)
        """
        print(f"📄 파일 분석 중: {file_path}")
        
        # 파일 파싱
        self.parser = CodeParser(file_path)
        functions = self.parser.extract_functions()
        
        print(f"🔍 {len(functions)}개의 함수 발견")
        
        # 각 함수에 주석 생성
        documented_code = self.parser.source
        
        for func in functions:
            if func['has_docstring']:
                print(f"⏭️  {func['name']}: 이미 docstring 존재, 스킵")
                continue
            
            print(f"✍️  {func['name']}: 주석 생성 중...")
            
            docstring = self.generator.generate_docstring(
                func['body'],
                style=self.style,
                language=self.language
            )
            
            if docstring:
                # 함수 정의 다음 줄에 docstring 삽입
                lines = documented_code.split('\n')
                func_line = func['lineno'] - 1
                
                # 들여쓰기 계산
                indent = len(lines[func_line]) - len(lines[func_line].lstrip())
                indented_docstring = '\n'.join(
                    ' ' * (indent + 4) + line 
                    for line in docstring.split('\n')
                )
                
                # docstring 삽입
                lines.insert(func_line + 1, indented_docstring)
                documented_code = '\n'.join(lines)
                
                print(f"✅ {func['name']}: 완료!")
        
        # 결과 저장
        output = output_path or file_path
        with open(output, 'w', encoding='utf-8') as f:
            f.write(documented_code)
        
        print(f"\n🎉 문서화 완료! 저장 위치: {output}")
    
    def process_directory(self, dir_path: str, recursive: bool = True):
        """
        디렉토리 내 모든 Python 파일을 처리합니다
        
        Args:
            dir_path: 처리할 디렉토리 경로
            recursive: 하위 디렉토리도 처리할지 여부
        """
        path = Path(dir_path)
        pattern = "**/*.py" if recursive else "*.py"
        
        py_files = list(path.glob(pattern))
        print(f"📁 {len(py_files)}개의 Python 파일 발견\n")
        
        for py_file in py_files:
            try:
                self.process_file(str(py_file))
                print()
            except Exception as e:
                print(f"❌ {py_file} 처리 중 오류: {e}\n")

# CLI 인터페이스
if __name__ == "__main__":
    import argparse
    
    parser = argparse.ArgumentParser(
        description="AI를 사용한 Python 코드 자동 문서화 도구"
    )
    parser.add_argument(
        "path",
        help="처리할 파일 또는 디렉토리 경로"
    )
    parser.add_argument(
        "--style",
        choices=["google", "numpy", "sphinx"],
        default="google",
        help="Docstring 스타일"
    )
    parser.add_argument(
        "--language",
        choices=["ko", "en", "ja"],
        default="ko",
        help="주석 언어"
    )
    parser.add_argument(
        "--output",
        help="출력 파일 경로 (파일 모드에서만)"
    )
    parser.add_argument(
        "--no-recursive",
        action="store_true",
        help="하위 디렉토리 제외"
    )
    
    args = parser.parse_args()
    
    documenter = AutoDocumenter(
        style=args.style,
        language=args.language
    )
    
    path = Path(args.path)
    
    if path.is_file():
        documenter.process_file(str(path), args.output)
    elif path.is_dir():
        documenter.process_directory(
            str(path),
            recursive=not args.no_recursive
        )
    else:
        print(f"❌ 경로를 찾을 수 없습니다: {args.path}")

사용 예시:

# 단일 파일 처리
python auto_documenter.py my_script.py

# 디렉토리 전체 처리
python auto_documenter.py ./src --style google --language ko

# 출력 파일 지정
python auto_documenter.py input.py --output output.py