SWA: 15. 코딩 규칙 (Coding Standards)

15.1. 주석

doxygen은 page라는 논리적인 단위와 file이라는 물리적인 단위로 소프트웨어를 문서화한다.

프로젝트 단위에서 문서화가 필요한 경우, 다음과 같이 doxygen을 사용한다:

태그기술
@mainpageDoxygen에서 @mainpage 태그는 문서의 메인 페이지를 정의하는 데 사용된다. 이 태그를 사용하여 프로젝트의 개요, 소개, 주요 기능, 사용법 등을 문서의 첫 페이지에 표시할 수 있다. 주로 프로젝트의 전체적인 설명과 중요한 정보를 제공하는 데 유용하다.
/**
@mainpage My Project Documentation
@section intro_sec Introduction
Welcome to the documentation for My Project.
@section install_sec Installation
To install this project, follow these steps:
- Step 1: Do this
- Step 2: Do that
@section usage_sec Usage
Here are some usage examples:
@code
int result = add(5, 3);
std::cout << "Result: " << result << std::endl;
@endcode
@section contact_sec Contact
If you have any questions, feel free to contact us at: support@example.com
*/
@pageDoxygen에서 @page 태그는 문서 내의 독립된 페이지를 정의하는 데 사용된다. 이는 특정 주제에 대한 상세한 설명이나 문서 내의 개별 섹션을 작성할 때 유용하다. @page 태그는 여러 섹션을 포함할 수 있으며, 문서 내에서 특정 주제를 다루는 데 적합하다.
/**
@page mypage My Custom Page
@section intro_sec Introduction
This is the introduction section of my custom page.
@section usage_sec Usage
Here is how you use this feature:
- Step 1: Do this
- Step 2: Do that
@section example_sec Example
Here is an example:
@code
int result = add(5, 3);
std::cout << "Result: " << result << std::endl;
@endcode
*/
@tableofcontentsDoxygen에서 @tableofcontents 태그는 문서 내에서 자동으로 목차를 생성하는 데 사용된다. 이를 통해 문서의 각 섹션과 하위 섹션으로 쉽게 이동할 수 있다. 목차는 일반적으로 메인 페이지나 큰 섹션의 시작 부분에 추가된다.
/**
@mainpage My Project Documentation
@tableofcontents
@section intro_sec Introduction
This is the introduction section of the documentation.
@section install_sec Installation
This section explains how to install the project.
@section usage_sec Usage
This section describes how to use the project, including examples and detailed explanations.
*/
@subpageDoxygen에서 @subpage 태그는 이미 정의된 페이지의 하위 페이지를 생성하는 데 사용된다. 이를 통해 문서의 계층 구조를 만들고, 특정 주제를 보다 세분화하여 설명할 수 있다. @subpage 태그는 상위 페이지의 일부로 간주되어, 관련 정보를 보다 체계적으로 정리하는 데 도움을 준다.
// 상위 페이지
/**
@page mainpage Main Page
@section main_intro Introduction
This is the main page of the documentation.
@section subpages Subpages
Here are some related topics:
- @subpage subpage1
- @subpage subpage2
*/// 하위 페이지
/**
@page subpage1 Subpage 1
@brief This is the first subpage.
@section subpage1_intro Introduction
This section provides an introduction to Subpage 1.
*/
/**
@page subpage2 Subpage 2
@brief This is the second subpage.
@section subpage2_intro Introduction
This section provides an introduction to Subpage 2.
*/
@sectionDoxygen에서 @section 태그는 문서 내에서 새로운 섹션을 생성하는 데 사용된다. 이를 통해 문서를 구조화하고, 특정 주제나 항목에 대한 설명을 체계적으로 정리할 수 있다. @section 태그는 섹션 제목과 섹션 내용을 포함하며, 섹션을 논리적으로 나눌 수 있다.
/**
@mainpage My Project Documentation
@section intro_sec Introduction
This is the introduction section of the documentation. Here, you provide an overview of the project.
@section install_sec Installation
This section explains how to install the project.
@section usage_sec Usage
This section describes how to use the project, including examples and detailed explanations.
*/
@subsectionDoxygen에서 @subsection 태그는 @section 태그 아래에 하위 섹션을 생성하는 데 사용된다. 이를 통해 문서를 더 세분화하고 체계적으로 구성할 수 있다. @subsection 태그는 상위 섹션을 논리적으로 나누어 더 자세한 정보를 제공하는 데 유용하다.
/**
@mainpage My Project Documentation
@section intro_sec Introduction
This is the introduction section of the documentation.
@subsection intro_background Background
This subsection provides background information about the project.
@subsection intro_objectives Objectives
This subsection outlines the main objectives of the project.
@section install_sec Installation
This section explains how to install the project.
@subsection install_requirements Requirements
This subsection lists the requirements for installation.
@subsection install_steps Steps
This subsection provides step-by-step instructions for installation.
*/
-, *Doxygen에서 불릿 리스트를 생성하려면, 하이픈(-) 또는 별표(*)를 사용한다.
/**
@brief This function does something useful.
The main steps involved are:
- Step 1: Initialize variables.
- Step 2: Process data.
- Step 3: Return results.
*/
void usefulFunction() {
// Function implementation
}/**
@brief This function does something useful.
The main steps involved are:
* Step 1: Initialize variables.
* Step 2: Process data.
* Step 3: Return results.
*/
void usefulFunction() {
// Function implementation
}

위에서,

  • main project는 @mainpage를 사용한다.
  • 그 외 프로젝트는 @page를 사용한다.
  • @page는, 선택적으로, @section과 @subsection을 이용하여 논리적으로 구분한다.
  • @page, @section, @subsection은 클래스, 함수 등을 포함한다.

파일 수준에서 문서화가 필요한 경우 다음과 같이 doxygen을 사용한다:

태그기술
@fileDoxygen에서 @file 태그는 파일 전체에 대한 주석을 추가하는 데 사용된다. 주로 파일의 목적, 파일에 포함된 주요 클래스나 함수, 그리고 파일의 기능을 설명한다. 이를 통해 파일에 대한 개요와 중요한 정보를 문서화할 수 있다.
/**
@file example.cpp
@brief This file contains the implementation of basic arithmetic operations.
@details
This file implements functions for addition, subtraction,
multiplication, and division of integers. It also includes
error handling for division by zero.
@author Your Name
@date 2024-12-22
*/
include
include
/**
@brief Adds two integers.
@param a The first integer.
@param b The second integer.
@return The sum of the two integers.
*/
int add(int a, int b) {
return a + b;
}
/**
@brief Subtracts the second integer from the first.
@param a The first integer.
@param b The second integer.
@return The difference of the two integers.
*/
int subtract(int a, int b) {
return a - b;
}
/**
@brief Multiplies two integers.
@param a The first integer.
@param b The second integer.
@return The product of the two integers.
*/
int multiply(int a, int b) {
return a * b;
}
/**
@brief Divides the first integer by the second.
@param a The numerator.
@param b The denominator.
@return The result of the division.
@throws std::invalid_argument If the denominator is zero.
*/
int divide(int a, int b) {
if (b == 0) {
throw std::invalid_argument("Denominator cannot be zero");
}
return a / b;
}
@brief아래 표의 @brief 참고
@detail아래 표의 @detail 참고

클래스, 함수, 변수 수준에서 문서화가 필요한 경우 다음과 같이 doxygen을 사용한다:

태그기술
@briefDoxygen에서 @brief 태그는 함수, 클래스, 변수 등의 간단한 설명을 제공하는 데 사용된다. 주로 한 줄 또는 두 줄 정도의 짧고 간결한 설명을 작성하여 해당 항목의 주요 목적이나 기능을 요약한다. @brief태그는 Doxygen이 생성하는 문서의 개요 섹션에 표시된다.
/**
@brief This function calculates the square of a number.
*
This function takes an integer input and returns its square.
@param number The integer to be squared.
@return The square of the input number.
*/
int square(int number) {
return number * number;
}
@detailDoxygen에서 @details 태그는 함수, 클래스, 변수 등의 항목에 대해 더 자세한 설명을 제공하는 데 사용된다. 이 태그는 일반적으로 @brief 태그와 함께 사용되며, @brief 태그는 간단한 요약을 제공하는 반면 @details 태그는 더 심층적인 설명을 포함한다.
/**
@brief This function calculates the square of a number.
*
@details
This function takes an integer input and returns its square.
It performs a simple multiplication of the input number by itself.
Example usage:
@code
int result = square(5); // result will be 25
@endcode
@param number The integer to be squared.
@return The square of the input number.
*/
int square(int number) {
return number * number;
}
@param Doxygen에서 @param 태그는 함수나 메서드의 매개변수를 문서화하는 데 사용된다. 이 태그를 사용하여 매개변수의 이름과 설명을 제공하여, 함수의 사용 방법을 보다 명확하게 이해할 수 있도록 한다.
/**
@brief Adds two integers.
*
@param a The first integer to be added.
@param b The second integer to be added.
@return The sum of the two integers.
*/
int add(int a, int b) {
return a + b;
}

Doxygen은 @param [in], @param [out], @param [in, out] 태그를 사용하여 함수의 매개변수에 대해 입력, 출력, 입력 및 출력을 명확하게 구분하여 설명할 수 있다.
@returnDoxygen에서 @return 태그는 함수나 메서드가 반환하는 값을 문서화하는 데 사용된다. 이를 통해 함수의 반환값이 무엇이며 어떤 의미를 가지는지 명확히 설명할 수 있다. 주로 함수의 반환 타입이 무엇인지, 반환값이 어떤 상황에서 어떻게 사용되는지를 설명한다.
/**
@brief Adds two integers.
@param a The first integer to be added.
@param b The second integer to be added.
@return The sum of the two integers.
*/
int add(int a, int b) {
return a + b;
}

프로젝트, 파일, 클래스, 함수, 변수 등에서 문서화를 위해 사용할 수 있는 공통적인 doxygen 태그는 다음과 같다:

태그기술
@bugDoxygen에서 @bug 태그는 코드에 존재하는 알려진 버그를 문서화하는 데 사용된다. 이를 통해 개발자는 해당 버그에 대한 정보를 쉽게 공유하고 추적할 수 있으며, 나중에 문제를 해결할 때 참고할 수 있다.
/**
@brief Divides two integers.
@param a The numerator.
@param b The denominator.
@return The result of the division.
@bug This function does not handle division by zero.
It will cause a runtime error if b is zero.
*/
int divide(int a, int b) {
return a / b;
}
@preDoxygen에서 \pre 태그는 함수나 메서드가 호출되기 전에 충족되어야 하는 전제 조건(preconditions)을 설명하는 데 사용된다. 이는 함수가 올바르게 동작하기 위해 필요로 하는 조건이나 가정을 명시한다.
/**
@brief Divides two integers.
@param a The numerator.
@param b The denominator.
@return The result of the division.
@pre The denominator b must not be zero.
*/
int divide(int a, int b) {
if (b == 0) {
throw std::invalid_argument("Denominator cannot be zero");
}
return a / b;
}
@noteDoxygen에서 @note 태그는 특별한 주의가 필요한 정보나 중요한 참고 사항을 강조하는 데 사용된다. 이 태그를 사용하면 독자가 함수나 클래스의 중요한 부분에 주목할 수 있도록 돕는다.
/**
@brief Calculates the factorial of a number.
*
@param n The number to calculate the factorial for.
@return The factorial of the number.
@note This function uses recursion and may cause a stack overflow for large values of n.
*/
int factorial(int n) {
if (n <= 1) return 1;
else return n * factorial(n - 1);
}
@todoDoxygen에서 @todo 태그는 코드 내에서 앞으로 해야 할 작업이나 개선사항을 문서화하는 데 사용된다. 이 태그를 통해 개발자나 팀원이 아직 완료되지 않은 작업을 쉽게 추적하고, 나중에 해당 작업을 처리할 수 있도록 도와준다.
/**
@brief Calculates the sum of two integers.
@param a The first integer to add.
@param b The second integer to add.
@return The sum of the two integers.
@todo Add error handling for overflow cases.
*/
int add(int a, int b) {
return a + b;
}
@refDoxygen에서 @ref 태그는 문서 내의 특정 섹션이나 항목을 참조할 때 사용된다. 이를 통해 문서의 다른 부분으로 쉽게 이동할 수 있는 링크를 제공하여, 문서의 가독성과 탐색성을 높일 수 있다.
/**
@brief Adds two integers.
This function adds two integers and returns the result.
For more information, see @ref add_function_details.
@param a The first integer to add.
@param b The second integer to add.
@return The sum of the two integers.
*/
int add(int a, int b) {
return a + b;
}
/**
@brief Detailed description of the add function.
@section add_function_details
This section provides more detailed information about the add function,
including its usage, performance considerations, and examples.
*/
@seeDoxygen에서 @see 태그는 현재 문서화된 항목과 관련된 다른 문서나 항목을 참조할 때 사용된다. 이는 독자가 추가적인 정보를 얻거나 관련된 부분을 쉽게 탐색할 수 있도록 돕는다. @see 태그는 주로 함수, 클래스, 변수 등과 연결된 유용한 정보나 관련 문서를 연결하는 데 사용된다.
/**
@brief Adds two integers.
This function adds two integers and returns the result.
@param a The first integer to add.
@param b The second integer to add.
@return The sum of the two integers.
@see subtract()
@see multiply()
*/
int add(int a, int b) {
return a + b;
}
@warningDoxygen에서 @warning 태그는 코드의 사용 시 주의해야 할 중요한 경고 사항을 문서화하는 데 사용된다. 이 태그를 통해 특정 함수나 메서드, 클래스 등을 사용할 때 발생할 수 있는 위험이나 주의사항을 강조할 수 있다. 이를 통해 개발자는 코드 사용 시 주의해야 할 점을 명확히 이해할 수 있다.
/**
@brief Divides two integers.
@param a The numerator.
@param b The denominator.
@return The result of the division.
@warning The denominator must not be zero.
If the denominator is zero, the function will cause a runtime error.
*/
int divide(int a, int b) {
if (b == 0) {
throw std::invalid_argument("Denominator cannot be zero");
}
return a / b;
}
Tagged:

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다