루비로 작성한 프로그램에 대해 문서를 제출할 일이 생겼다. RDOC을 이용하면 간단하게 HTML, XML, chm 형식의 문서를 뽑아 낼 수 있다. 주석을 충분히 달아 놓기만 했다면...

RDOC을 이용해서 문서화할 수 있도록 주석을 다는 법에 대해 알아보자.

RDOC 주석을 위한 특별한 시작은 없다. 클래스나 메쏘드 위의 주석은 모두 rdoc에 의해 해석된다. 주석의 작성 형식은 전체적으로 간단하고 실용적이며, 위키의 포맷과 비슷하다. 어렵지 않다.

리스트 표현

숫자, *, - 로 시작되는 문장은 리스트로 표현된다.

1. # * List item 1
2. # * List item 2

[] 는 다음 처럼 단어 설명에 사용하면 좋다.

1. # [고앙이]   small domestic animal 

인덴트

스페이스 두개로 인덴트가 표현된다. 리스트 안에 리스트를 표현하고 싶으면 다음과 같이 할 수 있다.

1. #
2. # - list 1
3. #   - list 1.1
4. #     - list 1.1.1

강조

• <b> </b> 는 글씨를 진하게 한다.
• <tt> </tt> 는 글씨를 typewriter 체로 한다.
• <em> </em> 은 글씨를 이택릭체로 한다.
• = 로 시작하면 헤드라인을 보여준다.

1. # <em>text</em>
2. # <b>text</b>
3. # <tt>text</tt>
4. # = Level One Heading 
5. # == Level Two Heading
6. # === Level Three Heading
7. # ==== Level Four Heading

rdoc에 포함시키지 않기

주석중 rdoc에 포함시키기 원치 않은 부분이 있다면 #-- 를 이용할 수 있다. #-- 이하의 부분은 rdoc에 포함되지 않는다. 다시 포함시키고 싶다면 #++를 이용한다.

1. # This is RDOC document.
2. #--
3. # Not included in RDOC from here
4. #++
5. # Now included again

상수를 포함시키고 싶지 않다면 다음과 같이 #:nodoc: 를 이용한다.

1. OsInfo = { #:nodoc:
2.                 "Linux" => "Linux", #:nodoc:  
3.                  "Unknown" => "Unknown" #:nodoc:
4. } #:nodoc:

#:doc:  은 반대로 포함되지 않는 부분을 포함시킨다. 특정한 private method를 주석에 포함시키고 싶을 때 유용하다.

하이퍼링크

http, ftp, mailto, www 로 시작되는 문장은 알아서 하이퍼링크로 치환시켜 준다. 또한 이미지 URL의 경우는 알아서 <img> 태그로 변환시켜 준다.
클래스나 메쏘드 이름과 같은 단어는 알아서 하이퍼링크를 생성해 준다. 굿!

참조

http://rdoc.sourceforge.net/doc/index.html