Doxygen 사용법

협업을 하면 누구나 느끼겠지만 사람에 따라 코딩 스타일이 천차 만별이다. 

내가 짠 코드를 몇 년뒤에 봐도 '이게... 뭐하는 함수지' 라는 생각이 들 때도 있는데, 

남이 짠 코드는 오죽하겠는가...!

 

그렇다고 코드 이해를 돕는답시고 소스코드 중간중간에 주석을 임의로 집어넣으면

오히려 가독성이 더 떨이지는 경우가 허다하다. 

 

이런 것을 방지하기 위해서 꼭 쓰이는 것이 바로 Doxygen이다. 

물론 best case는 doxygen도 필요없이 누가 봐도 명쾌한 코드를 짜는 것이지만

실제로 그렇게 되기란 쉽지 않다.

 

Doxygen을 통해서 별도의 문서를 만들지 않고도 코드의 API document를 만들 수 있다.

 

이번 포스팅에서는 GUI를 사용하는 방법은 다루지 않고, 

오직 터미널로 doxygen을 작성하는 방법만 다룰 것이다.

 

예시) OpenCV doxygen

 

---

 

Installation

sudo apt-get update -y
sudo apt-get install doxygen

 

 

 

Code

설치가 완료되었으면 doxygen 적용을 원하는 코드에 가서

doxygen 문법에 따라 주석을 작성한다.

 

example code)

#include <iostream>


/**
 * @class myClass
 * @brief simple description for myClass
 * @details detailed description for myClass
 */
class myClass
{
private:
  int value_;

public:
  myClass(int input) : value_(input)
  {}

  void print();
};

/**
 * @class myClass
 * @fn print
 * @brief print value on the terminal
 */
void myClass::print()
{
  std::cout << "Print value: " << this->value_ << std::endl;
}

int main()
{
  std::cout << "= Test code for Doxygen =" << std::endl;

  myClass c(0);
  c.print();
  
  return 0;
}

 

이 포스팅에서 디테일한 doxygen 문법에 대해서는 다루지 않는다. 

더 많은 doxygen 문법을 참조하려면 →  https://www.doxygen.nl/index.html

 

 

 

Configuration

코드가 다 작성되었으면 해당 프로젝트에 대한 configuration 파일을 만들어준다. 

configuration file에는 doxygen에 사용되는 다양한 변수들과 설정 값들이 들어가 있다.

아래 커맨드는 자신의 project가 있는 위치에서 실행한다.

 

default filename은 Doxyfile 이다.

configure 값을 변경하고 싶으면 아무 에디터를 사용해서 바꿔주면 된다.

# 1. Create configure file with specific filename
doxygen -g filename

# 2. Create configure file with default filename
doxygen -g

 

 

 

Generate document

이제는 Doxyfile을 사용해서 document를 만들어 보자.

doxygen Doxyfile

위 커맨드를 실행하면 현재 위치에서 새로운 폴더 두 개가 만들어진 것을 확인할 수 있다. 

> html

> latex

 

먼저 html 문서를 확인해보고 싶으면 웹 브라우저를 사용해서 열어볼 수 있다. 

cd html
firefox index.html

 

열어보면 아래와 같은 페이지가 뜬다.

 

여기서 Classes에 들어가보면 내가 만들었던 class들을 확인할 수 있다. 

그 중에서 내가 만들었던 myClass들 들어가보면 그 class에 속한 멤버 변수나 멤버 함수들을 확인할 수 있다.