/** * @brief 간결한 기능 설명 (50자 이내) * @details 상세 구현 내용 및 사용 예시 * @param[in] param1 입력 파라미터 설명 * @param[out] param2 출력 파라미터 설명 * @return 반환값 의미 및 가능한 값 * @retval 0 성공 시 반환값 * @retval -1 오류 발생 시 * @note 특이사항 또는 주의점 * @warning 잠재적 위험 요소 * @see 관련 함수/클래스 참조 */
3. 문서 구조화 전략
3.1 모듈화 기법
그룹핑을 통한 논리적 구성
c
/** * @defgroup network_module 네트워크 모듈 * @brief 네트워크 통신 관련 기능 집합 */
Doxygen을 효과적으로 활용하려면 프로젝트 초기 단계부터 문서화 전략을 수립해야 합니다. 주석 작성 표준의 일관된 적용과 지속적인 품질 관리가 핵심이며, 시각적 요소와 상호 참조 기능을 적극 활용하면 개발자 경험을 크게 향상시킬 수 있습니다. 문서화 작업을 단순한 의무가 아닌 코드 품질 관리의 핵심 도구로 인식하고 팀 차원의 체계적인 접근이 필요합니다.
- Variable: 변수
- Function: 함수
- Parameter/Argument: 매개변수/인수
- Array: 배열
- Pointer: 포인터
- Structure: 구조체
- Loop: 반복문
- Condition: 조건
- Index: 인덱스
- Counter: 카운터
- Buffer: 버퍼
- Memory: 메모리
- Error: 에러
- Result: 결과
3. 주석 패턴과 예문
3.1 함수 주석 패턴
/*
* Function: function_name
* Purpose: Brief description of what the function does
* Parameters:
* - param1: description
* - param2: description
* Returns: description of return value
*/
// 예시
/*
* Function: calculate_average
* Purpose: Calculates the average of an array of integers
* Parameters:
* - numbers: array of integers
* - size: number of elements in the array
* Returns: average value as a double
*/
double calculate_average(int numbers[], int size)
3.2 변수 선언 주석
int count = 0; // Counter for loop iterations
char *buffer; // Temporary storage for user input
bool is_valid = false; // Flag to check if input is valid
float temperature; // Current temperature in Celsius
3.3 코드 블록 주석
// Initialize all variables to default values
count = 0;
sum = 0;
average = 0.0;
/*
* Main processing loop
* Continue until user enters 'q' to quit
*/
while (input != 'q') {
// Process user input here
}
// Error handling section
if (result == NULL) {
printf("Error: Memory allocation failed\n");
return -1;
}
4. 상황별 주석 문장 템플릿
4.1 초기화 관련
- Initialize variables to zero
- Set default values for all parameters
- Clear the buffer before use
- Reset counter to starting position
4.2 조건문 관련
- Check if the input is valid
- Verify that the pointer is not NULL
- Test whether the array is empty
- Ensure the index is within bounds
4.3 반복문 관련
- Loop through all elements in the array
- Continue until end of file is reached
- Iterate over each character in the string
- Process each item in the list
4.4 메모리 관리 관련
- Allocate memory for the new structure
- Free previously allocated memory
- Check for memory allocation failure
- Release resources before exit
4.5 에러 처리 관련
- Handle invalid input gracefully
- Return error code if operation fails
- Display error message to user
- Exit program if critical error occurs
5. 실제 코드 예시
#include <stdio.h>
#include <stdlib.h>
/*
* Program: Simple Calculator
* Purpose: Performs basic arithmetic operations
* Author: Your Name
* Date: Current Date
*/
/*
* Function: add_numbers
* Purpose: Adds two integers and returns the result
* Parameters:
* - a: first integer
* - b: second integer
* Returns: sum of a and b
*/
int add_numbers(int a, int b) {
return a + b; // Simple addition operation
}
int main() {
int num1, num2; // User input numbers
int result; // Store calculation result
char operation; // Store selected operation
// Display welcome message
printf("Welcome to Simple Calculator\n");
// Get user input
printf("Enter first number: ");
scanf("%d", &num1);
printf("Enter second number: ");
scanf("%d", &num2);
// Perform calculation based on user choice
printf("Enter operation (+, -, *, /): ");
scanf(" %c", &operation);
// Process the selected operation
switch(operation) {
case '+':
result = add_numbers(num1, num2);
printf("Result: %d + %d = %d\n", num1, num2, result);
break;
case '-':
result = num1 - num2; // Subtract second from first
printf("Result: %d - %d = %d\n", num1, num2, result);
break;
default:
printf("Error: Invalid operation\n");
return -1; // Exit with error code
}
return 0; // Successful program termination
}
6. 주석 작성 시 주의사항
DO (권장사항)
복잡한 로직에 대한 설명 제공
함수의 목적과 매개변수 설명
에러 처리 방법 설명
알고리즘의 핵심 아이디어 설명
DON'T (피해야 할 것)
명백한 코드 반복 금지
// BAD: i++; // increment i by 1// GOOD: i++; // Move to next array element
너무 길거나 복잡한 설명 피하기
오래된 주석 방치하지 않기
7. 자주 사용하는 주석 템플릿
// TODO: Add error checking for this function
// FIXME: Memory leak possible here
// NOTE: This algorithm assumes sorted input
// WARNING: Do not modify this value directly
// HACK: Temporary solution, needs refactoring
# 프로젝트 이름
PROJECT_NAME = "My Project"
# 프로젝트 버전
PROJECT_NUMBER = "1.0"
# 입력 디렉토리 (소스 파일이 있는 경로)
INPUT = ./src
# 재귀적으로 하위 디렉토리 포함
RECURSIVE = YES
# 출력 디렉토리
OUTPUT_DIRECTORY = ./docs
# HTML 문서 생성
GENERATE_HTML = YES
# LaTeX 문서 생성 (필요한 경우)
GENERATE_LATEX = NO
# 파일 확장자 지정
FILE_PATTERNS = *.c *.cpp *.h *.hpp
# 소스 코드 포함
SOURCE_BROWSER = YES
# 그래프 생성 (graphviz 필요)
HAVE_DOT = YES
3. 문서 생성
doxygen Doxyfile
소스 코드 주석 작성법
Doxygen은 특별한 형태의 주석을 인식합니다. 주요 스타일들:
C/C++ 스타일 주석
/**
* @brief 두 정수를 더하는 함수
*
* 이 함수는 두 개의 정수를 받아서 그 합을 반환합니다.
*
* @param a 첫 번째 정수
* @param b 두 번째 정수
* @return 두 정수의 합
*
* @warning 오버플로우를 체크하지 않습니다
* @see subtract()
*
* Example:
* @code
* int result = add(5, 3); // result는 8
* @endcode
*/
int add(int a, int b) {
return a + b;
}
/*!
* \brief 클래스에 대한 설명
*
* 이 클래스는 간단한 계산기 기능을 제공합니다.
*/
class Calculator {
private:
int value; ///< 현재 값을 저장하는 변수
public:
/**
* @brief 생성자
* @param initial_value 초기값 (기본값: 0)
*/
Calculator(int initial_value = 0);
/// 소멸자
~Calculator();
};
주요 Doxygen 태그들
/**
* @file calculator.h
* @author 홍길동 (hong@example.com)
* @date 2024-01-15
* @version 1.0
* @copyright Copyright (c) 2024
*
* @brief 계산기 헤더 파일
* @details 기본적인 산술 연산을 수행하는 함수들을 정의
*/
/**
* @brief 함수 요약 설명
* @details 함수에 대한 자세한 설명
*
* @param[in] input_param 입력 매개변수
* @param[out] output_param 출력 매개변수
* @param[in,out] inout_param 입출력 매개변수
*
* @return 반환값 설명
* @retval 0 성공
* @retval -1 실패
*
* @note 특별한 주의사항
* @warning 경고사항
* @todo 향후 개선사항
* @bug 알려진 버그
*
* @see 관련 함수나 클래스
* @since 버전 1.0부터 사용 가능
* @deprecated 더 이상 사용되지 않음
*
* @code
* // 사용 예제
* int result = function_name(param);
* @endcode
*/
고급 기능 활용
1. 그룹핑 (Grouping)
/**
* @defgroup math_functions 수학 함수들
* @brief 기본적인 수학 연산 함수들
* @{
*/
/** @brief 덧셈 함수 */
int add(int a, int b);
/** @brief 뺄셈 함수 */
int subtract(int a, int b);
/** @} */ // end of math_functions group
#!/bin/bash
# generate_docs.sh
echo "프로젝트 문서 생성 중..."
# 기존 문서 삭제
rm -rf docs/
# Doxygen 실행
if doxygen Doxyfile; then
echo "✓ 문서 생성 완료"
echo "HTML 문서: docs/html/index.html"
# 웹 브라우저로 열기 (선택사항)
if command -v xdg-open > /dev/null; then
xdg-open docs/html/index.html
fi
else
echo "✗ 문서 생성 실패"
exit 1
fi
# 문서 크기 출력
echo "생성된 문서 크기: $(du -sh docs/ | cut -f1)"
팁과 모범 사례
1. 주석 작성 가이드라인
함수의 목적과 동작을 명확히 설명
매개변수와 반환값을 항상 문서화
예외 상황이나 제한사항 명시
사용 예제 포함
2. 문서 품질 향상
# 문서화되지 않은 항목 확인
doxygen Doxyfile 2>&1 | grep -i warning
# 그래프 품질 향상을 위한 설정
DOT_IMAGE_FORMAT = svg
INTERACTIVE_SVG = YES
DOT_GRAPH_MAX_NODES = 100