MCU 프로그래밍에서 알아두면 좋은 Doxygen 주석 블록(brief, param, retval, 등)에 대하여...

해당 포스팅은 개인적으로 MCU를 공부하면서 익힌 내용을 기억에 남기기 위한 작업의 일환으로 작성된 글로서
일부 내용에 오류가 있을 수도 있으니 참고하시기 바랍니다.

 

 

C언어로 MCU 프로그래밍을 할때
함수를 설명해주는 주석 블록을 Doxygen이라고 하는데,
어떤 기능이 있고 어떻게
사용하는지
알아보자.

 

 

반응형

 

Doxygen의 구성 요소

Doxygen 주석 블록은 함수, 변수, 클래스 등의 

코드 요소에 대한 설명을 제공하는 데 사용된다. 

주석 블록은 /** ... */로 감싸여 있으며, 

내부에 다양한 태그를 사용하여 설명을 추가한다. 

주요 태그와 그 의미는 다음과 같다

@brief: 함수나 클래스 등의 간단한 설명을 제공한다.
@param: 함수의 매개변수를 설명한다. [in], [out], [in,out] 등의 옵션을 사용하여 매개변수의 방향을 나타낼 수 있다.
@retval: 함수의 반환 값을 설명한다.
@return: 함수의 반환 값을 설명한다. @retval과 유사하지만, 주로 단일 반환 값에 사용된다.
@details: 함수나 클래스 등의 상세 설명을 제공한다.
@note: 주의 사항을 설명한다.
@warning: 경고 사항을 설명한다.
@code ... @endcode: 코드 블록을 포함한다.

 

예시를 통한 설명

 

다음은 Doxygen 주석 블록을 사용하여 함수의 문서를 작성하는 예시이다.

이 예시는 Metrology 주변 장치 레지스터를 초기화하는 함수를 설명한다.

 

/**
 * @brief  Initialize the Metrology peripheral registers to their default reset values.
 * @param[in]   None
 * @retval None
 * @details This function resets all the Metrology peripheral registers to their default values.
 *          It should be called during the system initialization to ensure that the Metrology
 *          peripheral is in a known state.
 * @note    This function does not return any value.
 * @warning Make sure that the Metrology peripheral is not in use before calling this function.
 */
void InitializeMetrology(void);

 

이 주석 블록은 InitializeMetrology 함수에 대한 설명을 제공한다.

 

각 태그의 의미는 다음과 같다.

@brief: 함수의 간단한 설명을 제공한다. 

여기서는 "Initialize the Metrology peripheral registers to their default reset values."라고 설명하고 있다.
@param[in]: 함수의 입력 매개변수를 설명한다. 이 함수는 입력 매개변수가 없으므로 None으로 표시되어 있다.
@retval: 함수의 반환 값을 설명한다. 이 함수는 반환 값이 없으므로 None으로 표시되어 있다.
@details: 함수의 상세 설명을 제공합니다. 이 함수는 Metrology 주변 장치 레지스터를 기본 초기화 값으로 설정하는 역할을 하며, 시스템 초기화 중에 호출되어야 한다고 설명하고 있다.
@note: 주의 사항을 설명한다. 이 함수는 반환 값이 없다는 점을 강조하고 있다.
@warning: 경고 사항을 설명한다. 이 함수를 호출하기 전에 Metrology 주변 장치가 사용 중이지 않은지 확인해야 한다고 경고하고 있다.

 

함수 구현

 

이제 함수의 구현을 살펴보자. 주석 블록은 함수의 선언부에 위치하며, 함수의 구현부는 주석 블록 아래에 위치한다

#include <stdint.h>

// Metrology 주변 장치 레지스터의 가상 주소
#define METROLOGY_REG_BASE 0x40000000
#define METROLOGY_REG_COUNT 10

// Metrology 주변 장치 레지스터를 나타내는 구조체
typedef struct {
    volatile uint32_t REG[METROLOGY_REG_COUNT];
} Metrology_TypeDef;

// Metrology 주변 장치 레지스터의 포인터
#define METROLOGY ((Metrology_TypeDef *) METROLOGY_REG_BASE)

/**
 * @brief  Initialize the Metrology peripheral registers to their default reset values.
 * @param[in]   None
 * @retval None
 * @details This function resets all the Metrology peripheral registers to their default values.
 *          It should be called during the system initialization to ensure that the Metrology
 *          peripheral is in a known state.
 * @note    This function does not return any value.
 * @warning Make sure that the Metrology peripheral is not in use before calling this function.
 */
void InitializeMetrology(void) {
    // Metrology 주변 장치 레지스터를 기본 초기화 값으로 설정
    for (int i = 0; i < METROLOGY_REG_COUNT; i++) {
        METROLOGY->REG[i] = 0x00000000; // 기본 초기화 값으로 설정
    }
}

 

이 함수는 Metrology 주변 장치 레지스터를 기본 초기화 값으로 설정한다. METROLOGY_REG_BASE는 Metrology 주변 장치 레지스터의 가상 주소를 나타내며, METROLOGY_REG_COUNT는 레지스터의 개수를 나타낸다.  Metrology_TypeDef 구조체는 Metrology 주변 장치 레지스터를 나타내며, METROLOGY는 이 구조체의 포인터이다.

함수 내부에서는 for 루프를 사용하여 모든 레지스터를 기본 초기화 값인 0x00000000으로 설정한다.

 

Doxygen을 사용한 문서 생성

 

Doxygen을 사용하여 문서를 생성하려면, 먼저 Doxygen 설정 파일인 Doxyfile을 생성해야 한다. Doxyfile은 Doxygen의 다양한 옵션을 설정할 수 있는 파일이다. Doxyfile을 생성하는 방법은 다음과 같다.

터미널을 열고 Doxygen이 설치된 디렉토리로 이동한 다음 명령어를 실행하여 Doxyfile을 생성한다.

 

doxygen -g

 

이 명령어는 기본 설정을 포함한 Doxyfile을 생성한다. 생성된 Doxyfile을 열어 필요한 옵션을 수정할 수 있다. 예를 들어, 소스 코드 파일의 경로를 설정하려면 INPUT 옵션을 수정한다.

 

INPUT = /path/to/your/source/code

 

Doxyfile을 수정한 후, 다음 명령어를 실행하여 문서를 생성한다.

 

doxygen Doxyfile

 

 

이 명령어는 Doxyfile에 설정된 옵션을 기반으로 문서를 생성한다. 생성된 문서는 HTML, LaTeX, RTF 등의 형식으로 저장된다. HTML 형식의 문서는 웹 브라우저를 사용하여 쉽게 열어볼 수 있다.

생성된 문서 예시
Doxygen을 사용하여 생성된 문서는 함수, 변수, 클래스 등의 설명을 포함한다. 예를 들어, InitializeMetrology 함수에 대한 문서는 다음과 같은 형식으로 생성될 수 있다.

InitializeMetrology 함수 문서

InitializeMetrology @brief Initialize the Metrology peripheral registers to their default reset values. @param[in] None @retval None @details This function resets all the Metrology peripheral registers to their default values. It should be called during the system initialization to ensure that the Metrology peripheral is in a known state. @note This function does not return any value. @warning Make sure that the Metrology peripheral is not in use before calling this function.

이 문서는 함수의 간단한 설명, 매개변수, 반환 값, 상세 설명, 주의 사항, 경고 사항 등을 포함하며, 이를 통해 함수의 사용법을 쉽게 이해할 수 있다.

 

결론

Doxygen 주석 블록을 사용하면 코드의 가독성을 높이고, 자동으로 문서를 생성하여 코드의 유지보수성을 향상시킬 수 있다. 주석 블록은 함수, 변수, 클래스 등의 코드 요소에 대한 설명을 제공하며, Doxygen을 사용하여 다양한 형식의 문서를 생성할 수 있다. 이 예시를 통해 Doxygen 주석 블록의 사용법과 문서 생성 과정을 이해할 수 있었기를 바란다.