로그인
FrontPage
RecentChanges
TitleIndex
FindPage
HelpContents
Doxygen
못 고치는 글
변경내역 보기
정보
Doxygen
Doxygen 설치
Doxygen 사용
Doxygen 에 그래프 기능 추가
스타일시트 바꾸기
Doxygen 에 맞는 Comment 붙이기 (2002년작성)
함수위에 코멘트
클래스위에 코멘트
멤버 변수에 코멘트
리스트로 표현하기
메인페이지 표현하기
새로운 페이지 만들기
요즘 쓰는 doxygen 사용 (2005년작성)
\brief
리스트
예외
Doxyfile 수정
code, endcode
version 업데이트
mainpage 등 추가적인 페이지
Reference
주의!! 나는 brief 를 매번 치기 귀찮아서 brief 를 망할 java 식으로 적고 있는데, doxygen 옵션(JAVADOC_AUTOBRIEF)을 바꾸는데 별 관심이 없다면 \brief 를 써라.
1. Doxygen 설치
http://www.doxygen.org 에서 다운받을수 있다. 물론 주석 다는것 자체에는 Doxygen 바이너리가 필요 없으므로 팀원 전체가 설치할 필요는 없다.
2. Doxygen 사용
오랜만에 돌리려니 하나도 기억이 안나서 고생했다. 혹시나 또 잊을까봐...
우선 쓰면 편하다는 DoxBar 는 전혀 도움이 안됐다. 그냥 Doxywizard 로 적당히 DoxyFile 을 적당한 폴더에 만들고 cmd 로 그 폴더에 가서 doxygen.exe 를 불러주는게 더 편했다.
위와 같이 해주면 폴더 안에 html 폴더에 생성된 파일이 들어가고, Html Workshop 을 이용해서 chm 으로 묶어줄수도 있다.
이때 doxygen 안에 파일을 추가할때, doxywizard 의 INPUT 탭에서 폴더를 추가후, 패턴에서 *.cpp 와 *.h 를 추가, 리커시브 옵션을 주고 걸러주는것이 편했다.( 파일을 하나씩 추가했을 경우 필터가 먹지 않아서, 큰용량의 바이너리파일 스캔중에 스택 오버플로... ) 또한, 다른 추가적인 페이지도 포함시키기 위해 .doxy 파일들도 인클루드 해줬다.
상세한 사용법은 Doxygen 설치시 깔리는 메뉴얼을 보면 된다.
3. Doxygen 에 그래프 기능 추가
http://www.research.att.com/sw/tools/graphviz/ 에 가서 graphviz 를 설치하고, doxywizard 의 DOT 탭 을 손본다. 반드시 설치하도록 하자.
4. 스타일시트 바꾸기
기본으로 들어있는 스타일시트는 보기 안좋다. Doxygen/CSS 의 스타일시트를 이용하면 그나마 나아진다.
음.. 요즘 버전은 그냥 써도 볼만 하다.
5. Doxygen 에 맞는 Comment 붙이기 (2002년작성)
Doxygen 의 comment 붙이는 유형은 크게 두가지, QT 와 Java 스타일이다. 내경우는 Java 스타일을 따르도록 했다. 왜냐하면, \ 가 한글 os ( 또는 한글 환경.. whatever )에선 역슬래시가 아니기 때문. 보기 안좋다!
5.1. 함수위에 코멘트
이때 주의점은 이 주석은 cpp 파일이 아닌 .h 파일에 붙어야 한다는것. 헤더파일을 깔끔하게 쓰는 개발자에겐 모양이 안날수도 있겠다.
추가: 신버전은 cpp 위에도 달수 있는것처럼 되어있는 문서를 봤는데.. 헤더위에 붙이는게 버릇이 되서 이부분에 대한 내용은 읽지않았다.
제목을 쓰는것에 @brief 를 쓰지 않고 자바 스타일을 따랐다는것에 주의. 아래 예처럼 첫줄에 . 으로 끝나도록 제목을 달았으면 Doxygen 이용시 JAVADOC_AUTOBRIEF 옵션을 켜줘야만 한다.
/** 원본파일을 설정한다 이 첫 문장은 제목이며, 제목은 마침표로 끝나야만 한다.
*
* 여기서 부터는 설명을 쓰면 된다.
* 설명은 적당히 편하게 써도 되지만, 포매팅을 위해서 html 태그나 doxygen command 를 포함할수도 있다.
*
* @author kinam
* @date 2002-11-04 오전 11:41:47
* @param strFile 원본파일의 path
* @return 성공여부
* @see GetSourceFile
*/
bool SetSourceFile(const CString& strFile);
그외 자주 쓸만한 커맨드로는, @todo, @bug, @code, @endcode, @exception 이 될것이다.
5.2. 클래스위에 코멘트
함수에 코멘트를 다는것과 같다.
/** 뭔가의 클래스 역시 제목은 마침표로 끝나야 하며 JAVADOC_AUTOBRIEF 옵션을 켜야만 한다.
*
* 클래스의 상세한 설명.
* 역시 함수때와 같다.
* Doxygen 의 옵션에 따라 이 클래스 설명이 문서 위에 나오도록 할수 있는데, 내 경우 그쪽이 더 보기 편하더라.
* DETAILS_AT_TOP 옵션을 주면 된다.
*/
class FooBar
{
};
5.3. 멤버 변수에 코멘트
멤버 변수에 짧은 커멘트를 달기 위해서는 ///< 의 행태로 주석을 달면 된다.
m_strUserID; ///< 사용자 아이디
m_strPassword; ///< 사용자 암호
m_iIQ; ///< 멍청한 정도
5.4. 리스트로 표현하기
/**
* A list of events:
* - mouse events
* -# mouse move event
* -# mouse click event\n
* More info about the click event.
* -# mouse double click event
* - keyboard events
* -# key down event
* -# key up event
*
* More text here.
*/
위와 같이, - 또는 -# 을 이용해서 bullet 표현을 할 수 있다.
5.5. 메인페이지 표현하기
내경우 MainPage.doxy 란 파일을 따로 만들어서, 그곳에 메인페이지 표현을 넣어놨다. *.doxy 파일들도 doxygen 대상으로 include 하는것을 잊지 말자.
Toggle line numbers
1
2 /** @mainpage 첫페이지
3
4 @section intro 소개
5 이 프로젝트는 멍멍멍 이다.
6
7 @section developer 개발자
8 참여 개발자들:
9 - 홍길동
10 - 고길동
11
12 @section history 역사
13 이 프로젝트는 가라이다.
14 - 멍멍멍
15 - 왈왈왈
16
17 @section Requirement 필요컴포넌트
18 - 눈
19 - 손
20
21 @section Links 참고페이지
22 @ref HowToKick
23 */
@ref 커맨드는 다른 페이지로의 링크를 걸어준다. 내경우 이 다른 페이지는 HowToKick.doxy 란 이름으로, 아래 섹션과 같은 내용을 넣어줬다. 이때 파일이름으로 링크가 걸리는것은 아니므로, @page HowToKick 만 어딘가에 있으면 된다.
5.6. 새로운 페이지 만들기
Toggle line numbers
1 /** @page HowToKick 차는법
2
3 차는법의 상세한 서술이다.
4
5
6 @section real 실생활에서의 차기
7 @code
8 왈왈왈;
9 @endcode
10
11
12
13 @section virtual 가상생활에서의 차기
14 @code
15 멍멍멍;
16 @endcode
17 */
이렇게 만든 페이지들은, 내가 링크를 걸어주지 않으면 메인 메뉴의 "관련된페이지들" 이란 곳에서 접근할수 있다. 즉 Doxygen 문서들을 볼때는 우선, 첫페이지("주요페이지" 라고 표현되어 있는) 를 본후 "관련된페이지들"을 보면 접근이 쉽다.
6. 요즘 쓰는 doxygen 사용 (2005년작성)
주의!! 위쪽에 쓴 부분과는 스타일이 좀 다르니 다른 페이지라고 생각하고 볼것
흠. 예전에 비해 몇가지를 좀 바꿨다. Emacs 를 쓰게 된것과 doxygen 이 업데이트 되면서 ui 가 변경된것이 그 이유. 예전에는 "@" 를 썼었는데, 지금은 Emacs 에서 코딩하면서 "\" 를 쓰게된것이라던지, doxygen ui 변경때문에 JAVADOC_AUTOBRIEF 을 켜주는게 귀찮아져서 \brief 를 쓰게된것 이 변경점.
doxymacs 도 한번 써봐야 하는데, 설치의 압박으로 아직 안깔아봤다. 이걸 쓰게 되면 문서 쓰는 스타일이 또 달라질듯?
6.1. \brief
javadoc 형태가 더 편하다고 생각되는데, doxygen ui 에서 c++ 에 최적화 해주는 옵션에서 이게 꺼져있어서 \brief 를 붙이는 스타일로 바꿔버렸다(shit)
Toggle line numbers
1 /** 예전엔 이렇게 제목을쓰고 JAVADOC_AUTOBRIEF 옵션을 줬었다. */
2 void main();
3
4 /**
5 * \brief 지금은 이렇게 쓴다 마침표 필요없다 옵션 따로 지정안해줘도 된다
6 */
7 void main();
8
9 /// 한줄로 하려면 이렇게 하면 된다 슬래시가 세개다
10 void main();
6.2. 리스트
depth 필요 없이 간단히 쓸때는 \li (\arg 와 동일) 을 쓰자
Toggle line numbers
1 /**
2 * \brief http server main loop
3 *
4 * \li accept 하며 대기
5 * \li 연결된 클라이언트로부터 http request 를 읽어서 ( httpd::recv_request )
6 * \li 그 요청에 맞는 적당한 명령을 pvr 에 내리고 ( httpd::do_something )
7 * \li 그 결과를 역시 rcxml 형태로 만들어서 (httpd::do_something )
8 * \li 클라이언트에 http response 해준다. (httpd::send_response )
9 */
10 void main_loop();
6.3. 예외
exception 을 자주 쓰게 되면서, 이놈도 자주 쓰게 됐다. 그냥 줄줄이 적어나가면 된다.
\exception mismatch_xml_tag_error 짝이 맞지 않는 태그가 입력된 경우
\exception invalid_xml_error 닫히지 않은 xml 이 입력된 경우
요렇게...
Toggle line numbers
1 /**
2 * \brief xml 이 완전하지 않은경우 sax2 가 던지는 예외
3 */
4 class invalid_xml_error : public std::exception {};
5
6 /**
7 * \brief xml 파싱도중 태그스택이 어긋날때 sax2 가 던지는 예외
8 *
9 * 즉, 열린태그가 다른 이름으로 닫혔을때 나는 에러로 tag 가 오타일
10 * 가능성이 높다.
11 */
12 struct mismatch_xml_tag_error : public std::runtime_error
13 {
14 mismatch_xml_tag_error(const char* s) : std::runtime_error(s) {}
15 };
16
17
18 /**
19 * \brief parse xml
20 * \param xml entire xml
21 * \exception mismatch_xml_tag_error 짝이 맞지 않는 태그가 입력된 경우
22 * \exception invalid_xml_error 닫히지 않은 xml 이 입력된 경우
23 */
24 void loadxml(const std::string& xml);
6.4. Doxyfile 수정
Doxywizard 로 대강 클릭질해서 만들면 디렉토리들이 절대경로로 적혀있다. 이놈들 Subversion 에 넣었다간 여러모로 피곤하니 상대경로로 모두 바꾸자.
이런식으로...
...
OUTPUT_DIRECTORY = ../doc/
...
INPUT = .
...
그리고 Makefile 등에서 doxygen 을 돌릴수 있도록 해주자.
doxy:
-doxygen
덤
CXX = g++
CXXFLAGS = -Wall
LDFLAGS =
ifeq ($(release),1)
CXXFLAGS += -DNDEBUG -O3
else
CXXFLAGS += -g
endif
ifeq ($(profile),1)
CXXFLAGS += -pg
endif
SRCS = main.cpp version.cpp svn_version.cpp log.cpp httpd.cpp httpreq.cpp test.cpp SAXClass.cpp sax2.cpp
OBJS = $(SRCS:.cpp=.o)
OUTPUT = ../bin/a.out
.PHONY: clean TAGS svn_version.cpp
all: svn_version.cpp TAGS $(OUTPUT)
%.o: %.cpp
@echo COMPILE $<
@$(CXX) -c $(CXXFLAGS) -o $@ $<
svn_version.cpp:
@echo SVN repository: `svnversion -n .`
@printf 'const char* svn_version(void) { const char* SVN_Version = "' > svn_version.cpp
@svnversion -n . >> svn_version.cpp
@printf '"; return SVN_Version; }\n' >> svn_version.cpp
TAGS:
@echo making tags
-@gtags
$(OUTPUT): $(OBJS)
@echo LINK $(OUTPUT)
@$(CXX) $(CXXFLAGS) -o $(OUTPUT) $(OBJS) $(LDFLAGS)
clean:
-rm -f $(OBJS) $(OUTPUT)
-rm -f core
doxy:
-doxygen
6.5. code, endcode
아무리 주절주절 달아봐야 몇달 지나면 기억 안나더라. 주석은 필요할때만 적당히 달고, 대신 코드(usage, example, test-code) 조각들을 class 앞에 달아두는게 뒤가 편하다. 가능하면 클래스는 minimal 하게 작성하고, 클래스마다 주석을 잘 달아두자. 클래스를 잘 나눠두면 멤버에는 굳이 주석이 필요 없다.
Toggle line numbers
1 /**
2 * \brief simple httpd module
3 *
4 * 아주 간단한 http 서버 코드로 최소한의 필요한 사항만 구현해 놓았다.
5 *
6 * \code
7 * httpd h(80); // 80 포트로 리슨을 하는 httpd instance
8 * h.main_loop(); // 소켓 연결을 기다렸다가 http 작업을 계속하는 루프
9 * \endcode
10 *
11 * 전체적인 모양을 보려면 main_loop 를 봐라.
12 */
13 class httpd
14 {
15 // 생략
16 };
Toggle line numbers
1 /**
2 * \brief 바이트 스트림에서 http_request 를 만들어 내는 클래스.
3 *
4 * POST,GET method 만 지원하며, POST,Post,post 의 경우가 아니라면 모두 GET 으로 처리된다.
5 *
6 * http request 가 완전할때까지, http request 를 읽는다.
7 * \code
8 * while(!request_.complete())
9 * {
10 * string buf = read_from_socket_or_file_whatever();
11 * request_.add(buf);
12 * }
13 * \endcode
14 *
15 * 모두 읽은 상태에서 필요한 값들은 이렇게 얻으면 된다.
16 * \code
17 * string method = request_.get_method(); // GET, POST 등
18 * string local_path = request_.get_local_path(); // method 가 요청하는 URL path
19 * string length = request_.get_header_value("content-length"); // 특정 헤더 값
20 * int length = request_.get_header_ivalue("content-length"); // 특정 헤더값의 atoi 값
21 * string body = request_.get_body(); // http request 의 body 부분
22 * \endcode
23 *
24 * \see httpd::recv_request
25 */
26 class http_request
27 {
28 // ...
29 };
6.6. version 업데이트
version 을 업데이트 하려면 Doxyfile 을 수정해줘야 하는 불편함이 있어서 version 명시를 하지 않고 쓰는데, FAQ 를 읽다보니 이런 방법이 있더라.
( cat Doxyfile ; echo "PROJECT_NUMBER=1.0" ) | doxygen -
If multiple options with the same name are specified then doxygen will use the last one. To append to an existing option you can use the += operator.
음. 하지만 나는 유닉스/윈도 모두에서 돌려야 하고.. 윈도에서는 윈용 bash 같은것 보다는 그냥 cmd 를 쓰니까 이방법은 쓸수가 없다. 후에 윈도의 shell 이 좋아지면 그때 써보자. 롱혼에 새로운 쉘이 달린다던데(codename MONAD) 그놈이 똘똘했으면 좋겠다.
6.7. mainpage 등 추가적인 페이지
전에는 doc 폴더 만들어서 *.doxy 또는 *.dox 라고 만들었었는데, *.doxy 나 *.dox 를 Doxyfile 파일 패턴에 추가해주기 귀찮더라. 그냥 간단하게, src 폴더 아래에 dox 라는 폴더를 만들고, *.h 헤더를 만들어서 주석만 주절주절 달고 있다. 예를들어 MAINPAGE.h 또는 INDEX.h 나, HOWTO-ADD-NEW-OPERATION.h 이런식으로..
Toggle line numbers
1 /** 고정폭때문에 cpp 주석을 썼다.
2
3 /project_root : project root
4 /src : 소스파일들은 죄다 여기
5 /include : 공통적으로 쓰는 헤더들은 여기 /root/include 로 만들때도 있다.
6 /dox : 여기에 doxygen 문서들 때려박는다. 확장자는 .h
7 /doc : ppt 문서등, 소스와 직접적인 연관이 없는(doxygen 외의) 문서들은 여기둔다
8 /scratch : 간단한 테스트 소스, 툴 소스들
9 /01.foo
10 /02.bar
11 /bin : build output 은 여기
12 */
7. Reference
http://bbs.kldp.org/viewtopic.php?t=49745
http://wiki.kldp.org/wiki.php/Doxygen tutorial 식의 강좌가 있다.
CategoryTool
참고:
Doxygen/CSS
http://www.doxygen.org
http://ndoc.sourceforge.net/ NDOC 이란건데...
http://docutils.sourceforge.net/ plain text 를 여러 문서로 바꿔주는건데.. 알아만 둬야지
검색어: 주석 문서생성 독시젠
2005-05-10 06:00:24에 dreamstorm가 마지막으로 고침
못 고치는 글
변경내역 보기
정보
MoinMoin Powered
Python Powered
MoinMoin 1.3.3 release, Copyright 2000-2004 by Juergen Hermann
getACL = 0.100s
run = 1.208s
send_page = 1.055s
send_page_content = 0.275s
total = 1.231s
댓글 없음:
댓글 쓰기