소스 코드 내에 header를 작성하는 것으로 문서화를 위한 준비는 모두 끝난다.ROBODoc의 header는 매우 간단하면서도 체계적으로 구성되어 있다.
Documentation을 위해 소스코드 내에 삽입되는 요소는 Header라고 한다. Header는 begin marker와 end marker, item으로 구성되어 문서화 작업의 한 블록을 이룬다. 다음의 예제를 보자.
/****f* module-1/killhim
* NAME
* killhim
* SYNOPSYS
* int killhim(char *name, char *method, int count)
* FUNCTION
* 대상과 수단, 횟수를 골라 방법하는 함수다.
* INPUT
* name -- 대상
* method -- 수단
* count -- 횟수
* RESULT
* 0 for success, else an error code return
******
* 여기에 쓰는 주석은 문서화 되지 않는다.
*/
int killhim(char *name,char *method, int count){
if((strcmp(name,"bush"))==0)
count *= 100;
while(count-- > 0)
hithim(name,method);
return 0;
} |
위의 예제는 하나의 header를 이루고 있다. 이 header는 아래의 killhim에 대한 주석이자 문서가 되는 것이다.
****f* module-1/killhim |
이 부분이 begin marker이다. 헤더가 시작됨을 표시한다. 플래그와 뒤의 계층에 대해서는 뒤에서 설명하겠다.
* NAME * killhim * SYNOPSYS * int killhim(char *name, char *method, int count) |
item 부분이다. item들은 정의되어 있으며 사용자 정의를 추가할 수도 있다.
****** |
end marker다. 이 표시를 기준으로 header는 끝난다. 이후에 이어지는 주석은 robodoc에 영향을 주지 못한다.
각각의 마크 앞에는 사용하는 언어의 주석이 붙게 된다. 다음은 각 언어별로 mark하는 방식이다.
/**** C, C++
*
***
//**** C++
//
//***
(**** Pascal, Modula-2
*
***
*)
{**** Pascal
*
***
*}
;**** M68K assembler
;
;***
**** M68K assembler
*
***
C **** Fortran
C
C ***
REM **** BASIC
REM *
REM ***
%**** LaTeX, TeX, Postscript
%
%***
#**** Tcl/Tk
#
#***
**** COBOL
*
***
--**** Occam
--
--***
|**** GNU Assembler
|
|***
!!**** FORTRAN 90
!!
!!*** |
header type은 현재 작성중인 헤더가 무엇에 대한 헤더인지를 알려준다. 즉, 함수에 대한 헤더인지 모듈에 대한 헤더인지에 대한 표시인 것이다. 헤더를 표시함으로써 인덱싱과 정렬을 효과적으로 할수 있게 된다.
앞의 begin marker ****f에서 "f"가 바로 헤더 타입이다. 지원하는 헤더 타입은 아래와 같다.
h -- 모듈(module in project) f -- 함수(function) s -- 구조체(structure) c -- 클래스(class) m -- 메소드(method) v -- 변수(variable) d -- 상수(constant) * -- 일반(generic header) |
ROBODoc에 정의된 item은 다음과 같으며, robodoc.rc파일을 이용해 추가할 수 있다.
NAME -- Item name plus a short description.
SYNOPSIS, USAGE -- How to use it.
FUNCTION, DESCRIPTION, PURPOSE -- What does it do.
AUTHOR -- Who wrote it.
CREATION DATE -- When did the work start.
MODIFICATION HISTORY, HISTORY -- Who has done which changes and when.
INPUTS, ARGUMENTS, OPTIONS, PARAMETERS, SWITCHES -- What can we feed into it.
OUTPUT, SIDE EFFECTS -- What output is made.
RESULT, RETURN VALUE -- What do we get returned.
EXAMPLE -- A clear example of the items use.
NOTES -- Any annotations
DIAGNOSTICS --Diagnostic output
WARNINGS, ERRORS -- Warning and error-messages.
BUGS -- Known bugs.
TODO, IDEAS -- What to implement next and ideas.
PORTABILITY -- Where does it come from, where will it work.
SEE ALSO -- References to other functions, man pages, other documentation.
METHODS, NEW METHODS -- OOP methods.
ATTRIBUTES, NEW ATTRIBUTES -- OOP attributes
TAGS -- Tag-item description.
COMMANDS -- Command description.
DERIVED FROM -- OOP super class.
DERIVED BY -- OOP sub class.
USES, CHILDREN -- What modules are used by this one.
USED BY, PARENTS -- Which modules do use this one.
SOURCE -- Source code inclusion.
/****f* module-1/killhim 에서 module-1/killhim에 해당하는 부분이 section이다. section은 문서의 계층화를 위해서 존재한다. 프로젝트/모듈/(함수 또는 변수나 class 등)으로 계층을 나누어 section을 활용하면 문서로 변환할 때 ROBODoc은 이를 인식하고 인덱싱해준다. 예를 들어 다음과 같은 구조의 프로젝트가 있다고 하자.
-ProjectA -- module1 -- function1
-- variable1
-- module2 -- function2
-- function3 |
이 경우 각각의 헤더는 다음과 같이 section으로 나눌 수 있다.
/****h* ProjectA/module1 ... /****h* ProjectA/module2 ... /****f* module1/function1 ... /****v* module1/variable1 ... /****f* module2/function2 ... /****f* module2/function3 ... |
이렇게 section을 지정한 후 ROBODoc을 이용해 HTML변환을 하면 다음과 같이 indexing 된다.
1 ProjectA/module1 1.1 module1/function1 1.2 module1/variable1 2 ProjectA/module2 2.1 module2/function2 2.2 moudle2/function3 .. |