DoxyGenSyntax

UserPreferences

1. 개요
2. 파일 설명
3. 클래스 설명
4. 구조체 설명
5. 함수 설명
6. 클래스 또는 구조체 내부 데이터 설명
7. 열거값 설명
8. 매크로 설명
9. 리스트 만들기
10. 주석 문자열 그대로 이용하기
11. 멤버 변수/함수 그룹 주석 달기
12. Dox 파일 문법

1 개요

개인적으로 자주 사용하는 DoxyGen 주석 포맷이다. 이외에도 유용한 태그들이 많으니, DoxyGen 헬프 파일을 참고하도록. 그리고 함수 헤더 같은 것 매번 타이핑해서 만들려면 죽음이니, 매크로의 사용은 필수다. VisualStudioMacro 페이지를 참고하시라.

2 파일 설명

파일의 제일 위에다 붙이는 것이 좋다.


//////////////////////////////////////////////////////////////////////////////
/// \file ChatterEliza.h
/// \author excel96
/// \date 2003.4.16
///
/// 원래 eliza는 문장 치환이 1군데에서 밖에 일어나지 않는 시스템이었으나,
/// 문장 치환이 일어날 수 있는 곳을 여러 군데로 만들기 위해 꽤 수정을 했다.
///
/// \todo
/// 유니코드 대비 할 것.
/// \bug
/// 버그 졸라 많다.
/// \warning
//////////////////////////////////////////////////////////////////////////////

3 클래스 설명

왠만하면 클래스 바로 위에 붙일 것.


//////////////////////////////////////////////////////////////////////////////
/// \class ChatterEliza
/// \brief 대화 시스템의 하나
///
/// ChatterEliza는 유저의 입력을 패턴으로 인식하여, 미리 준비된 대답 중에 
/// 하나를 적당한 치환을 통해 만들어내는 대화 시스템의 일종이다. 
///
/// ChatterEliza는 입력 패턴과 출력 패턴의 쌍으로 이루어진 데이터베이스를 가지고 
/// 있으며 입력을 받으면 이것과 매치하는 입력 패턴을 찾아내어 그것과 쌍이 되는
/// 출력 패턴을 근거로 응답을 생성한다. 예를 들면 
///
/// <pre>
/// Pattern  : %0 are you %1 
/// Response : Would you prefer it if I weren't %1 
/// </pre>
/// 
/// 라는 쌍을 이용하여, "Why are you looking at me?"에 대한 응답으로서 
/// "Would you prefer it if I weren't looking at you"를 생성한다는 말이다. 
//////////////////////////////////////////////////////////////////////////////

4 구조체 설명

왠만하면 구조체 바로 위에 붙이는 것이 좋다.


//////////////////////////////////////////////////////////////////////////////
/// \struct DatabaseManager::IMPL
/// \brief DatabaseManager 내부 데이터
/// 
/// 자세한 설명이 필요한가? 그냥 간단한 PIMPL일 뿐...
//////////////////////////////////////////////////////////////////////////////

5 함수 설명

왠만하면 함수 바로 위에 붙이는 것이 좋다.


//////////////////////////////////////////////////////////////////////////////
/// \brief 스트링 벡터를 화면에 출력하기 쉽게 하기 위한 유틸리티 함수
/// 
/// \param con 콘솔 객체
/// \param SV 출력할 스트링 벡터
/// \return Console& cout처럼 쭉 출력할 수 있도록 콘솔 객체를 다시 리턴한다.
//////////////////////////////////////////////////////////////////////////////
static Console& operator << (Console& con, vector<string>& SV)
{
    for (size_t i=0; i<SV.size(); i++) { con << "[" << SV[i] << "]"; }
    return con;
}

6 클래스 또는 구조체 내부 데이터 설명

멤버 변수 바로 뒤에 붙여도 되고...


CONTEXT_MAP     ContextMap; ///< 스레드별 Connection 객체의 집합
CriticalSection ContextCS;  ///< ConnectionContext 객체 생성을 위한 락
unsigned int    PingTime;   ///< 다음 핑 때릴 시간

멤버 변수 위에 붙여도 된다. 단 '<'는 떼야 된다.


/// 스레드별 Connection 객체의 집합
CONTEXT_MAP     ContextMap; 

/// ConnectionContext 객체 생성을 위한 락
CriticalSection ContextCS;  

/// 다음 핑 때릴 시간
unsigned int    PingTime;   

7 열거값 설명

//////////////////////////////////////////////////////////////////////////////
/// 육성 큐에다 집어넣을 수 있는 행동의 종류
//////////////////////////////////////////////////////////////////////////////
enum TrainClass
{
    TRAIN_MAGIC = 0,      ///< 마법
    TRAIN_EXERCISE,       ///< 운동
    TRAIN_COOKING,        ///< 요리
    TRAIN_RECREATION,     ///< 놀이
    TRAIN_CLEANSING,      ///< 청소
    TRAIN_READING,        ///< 독서
    TRAIN_REST,           ///< 휴식
    TRAIN_MAX             ///< 배열을 위한 맥스값
};

8 매크로 설명

매크로 위에다 붙여도 되고...


/// \a X와 \a Y 중 큰 값을 리턴하는 매크로
#define MAX(X, Y) ((X) > (Y) ? (X) : (Y))

바로 옆에다 붙여도 된다.


#define MAX(X, Y) ((X) > (Y) ? (X) : (Y)) ///> \a X와 \a Y 중 큰 값을 리턴하는 매크로

간단 설명, 자세한 설명 따로 붙이고 싶다면...


/// \brief \a X와 \a Y 중 큰 값을 리턴하는 매크로
/// 
/// 왠만하면 두 인수를 같은 타입으로 줘야 안전할 것이다.
#define MAX(X, Y) ((X) > (Y) ? (X) : (Y))

9 리스트 만들기

파이썬에서 하는 것처럼 칸을 딱딱 맞춰서 '-' 문자를 사용하면 된다. '-' 문자 뒤에는 한 칸 띄우도록.


/// - <b>10 11 12</b>
///   모든 것이 순서대로 왔다. LastID는 매번 증가한다.
///
/// - <b>11 10 12</b>
///   먼저 LastID가 11로 증가한다. 9->11로 변했으므로, 10의 값이 OmitList에
///   추가된다. 다음으로 10이 오면 리스트에 존재하므로, 실행한다. 그리고 
///   리스트에서 데이터를 삭제한다. 12는... 정상적이므로 실행한다.
/// 
/// - <b>10 10 11</b>
///   제일 처음 오는 10은 당연히 정상적으로 실행된다. 두번째로 오는 10은 
///   LastID값에 의해서 무시된다. 11은 다시 정상적으로 실행된다.

10 주석 문자열 그대로 이용하기

가끔씩 주석 내부에 코드를 넣거나, 표 등을 텍스트로 그려넣는 경우가 있는데, 이럴 경우에는 pre 태그를 이용하면 된다.


/// <pre>
/// Thread::run()
/// {
///     while (m_bContinue)
///     {
///         ...
///     }
/// }
/// </pre>

/// <pre>
/// +-------------+--------------+------+-----+---------+-------+
/// | Field       | Type         | Null | Key | Default | Extra |
/// +-------------+--------------+------+-----+---------+-------+
/// | ID          | varchar(50)  |      | PRI |         |       |
/// | Password    | varchar(50)  |      |     |         |       |
/// | ..........................................................|
/// | LoginStatus | int(11)      |      |     | 0       |       |
/// +-------------+--------------+------+-----+---------+-------+
/// </pre>

11 멤버 변수/함수 그룹 주석 달기

간단한 함수나 멤버 변수가 많은 경우, 이들 각각에 설명을 따로 다는 것이 귀찮을 때가 있다. 그럴 때는 다음과 같은 방식으로 주석을 달아주면 좋다. 꼭 멤버 변수나 함수일 필요는 없다. 클래스 외부에서도 사용할 수 있다. 다만 그룹 내에 그룹을 다시 집어넣을 수는 없다. 안타깝다.


/// \name 객체의 별명과 관련된 함수들
/// \{
/// \brief 객체의 별명을 반환하거나 세팅한다.
/// 
/// 객체의 별명은 상당히 많이 사용되니, 될 수 있으면 짧게 하도록.
string getName() const;
void setName(const string& name);
/// \}

12 Dox 파일 문법

.dox 파일을 이용해, 메인 페이지나 기타 페이지 등을 생성할 수 있다. 뭐, 꼭 다른 파일에 아래의 내용을 포함시킬 필요까지는 없지만, 소스와 관련되지 않은 내용을 소스에 기록해두는 것도 좀 찝찝하니까. FILE_PATTERN에 *.dox 를 포함시키는 것을 잊지 말자.


/** @mainpage Common Library 
 <center>http://somewhere.in.the.web</center> 
 <hr> 
  
클라이언트와 서버가 공용으로 사용하는 라이브러리 중의 하나로서, 
주로 디버깅 관련 기능이나 간단한 유틸리티 기능들을 포함한다. 
전체 프로젝트의 가장 베이스가 되는 라이브러리이므로, 거의 
모든 라이브러리나 실행 파일 프로젝트에서 이 라이브러리를 참조한다. 
그러므로 쓸데없는 기능을 포함시켜서 덩치를 불리지 말고,  
모두가 사용하는 기능만을 가질 수 있도록 해야 한다. 
  
@ref Notes 
 
 
*/ 
 
/** 
@page Notes 주의할 점 
 
@section First What is First? 
 
하나면 하나지 둘이겠느냐... 
 
@section Second What is Second? 
 
둘이면 둘이지 셋이겠느냐? 
*/ 

• see also DoxyGen
  

• CategoryTools