파이썬에서 문자열은 " 나 ' 로 표시가 된다.
하지만 HTML의 <PRE> 태그 처럼 """ 를 사용하면 엔터표시 없이 보이는대로 출력해주는 특이한(?!) 문법이 존재한다.
처음에는 도대체 이녀석을 왜쓸까? 했는데,
python 자체 util 인 pydocs가 문서화를 하는데 __doc__ 사용한다고 한다.

아래는 파이썬 튜토리얼중 문자열에 대한 부분인데,
단순하게 사용법을 출력하기 위해 \n 없이 문자열을 입력하는 것을 보여준다.

Or, strings can be surrounded in a pair of matching triple-quotes: """ or '''. End of lines do not need to be escaped when using triple-quotes, but they will be included in the string.

print """
Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to
"""

produces the following output:
Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to

[링크 : http://docs.python.org/tutorial/introduction.html#strings]

파이썬 class 문서로서, """A Simple example class"" 는
MyClass.__doc__ attribute로 문자열로 인식이 되며, pydocs나 doxygen에서
이를 이용하여 함수의 간략한 설명을 넣는데 이용될 수 있다.

class MyClass:
    """A simple example class"""
    i = 12345
    def f(self):
        return 'hello world'

[링크 : http://docs.python.org/tutorial/classes.html]


위는 전형적인 python 의 주석 스타일이며, 아래는 doxygen을 위한 주석 스타일이다.
그러고 보니.. 파이썬도 #를 이용한 주석을 인정하는군..(Makefile이나 쉘 스크립트는 #로 시작하는 줄은 주석으로 인식함)

For Python there is a standard way of documenting the code using so called documentation strings. Such strings are stored in __doc__ and can be retrieved at runtime. Doxygen will extract such comments and assume they have to be represented in a preformatted way.

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass



## @package pyexample
#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

[링크 : http://www.stack.nl/~dimitri/doxygen/docblocks.html]

신고
Posted by 구차니

댓글을 달아 주세요

doxygen은 html / pdf / rtf / xml 타입으로
함수들의 목록이나 사용방법 메뉴얼을 만들어 주는 독한 녀석이다.
가장 익숙한 유사한 녀석은
API tree view인데
[링크 : http://java.sun.com/j2se/1.4.2/docs/api/]

이런녀석이 doxygen 류의(자바는 javadoc 이라고 자체 지원하는듯) 프로그램을 통해 자동 생성되는 녀석이다.
이런걸 왜하나면.. 프로그램 문서화의 일환이기도 하고, 좋게 말하면 인수인계 안하고
"소스를 보면 다 보이르니라~" 라고 발빼기 편하기 위함이다.(응?)


doxygen은 굳이 doxygen 문법으로 주석을 달아주지 않아도, 일단 생성은 해준다.
자세한 사용방법이나 설명서는 별도로 주석에 포함하여 작업을 해주어야 하지만 말이다.

Step 1. Project 탭
            Doxygen을 실행시키면 아래와 같은 화면이 나오고
           "Step 1:Specify ..." 부분에 프로젝트 루트의 경로를 입력한다.
            그리고 Project name / version or id 에는 임의로 넣어주어도 되니 대충 패스
            source code directory 에는 프로젝트 루트를 입력하고 "Scan recursively"를 반드시 체크해야
            빠짐없이 소스를 검색해서 api 문서를 작성해준다.
            Destination directory는 생성된 html 이나 pdf 파일이 저장될 위치로,
            프로젝트 내에 doc 폴더를 만들거나, 다른 경로로 지정해주어도 무방하다.

            단, 경로명에 한글을 지원하지 않으므로,
            중간에 "바탕 화면" 이런게 들어가면 작동하지 못하니 경로를 옮겨야 한다.


Step 2. Mode 탭
           출력될 내용을 고르는 것으로, 많은 양의 출력을 원하면 아래와 같이
           All Entities / Include cross-referenced source code in the output을 선택한다.
           그리고 doxygen이 인식할 언어를 고르는 건, 프로젝트의 언어에 맞게 골라주면 된다.


Step 3. Output 탭
           이 탭은 결과물을 어떤형식으로 저장할지에 대한 부분이다.
           HTML은 원래 웹에서 사용하는 용도로 만들어지긴 하지만,
           가장 알록달록해서 HTML로 저장해서 로컬에서 봐도 꽤 유용하다.
           API 탐색에 익숙한 tree 구조로 만들어주는게 좋기에 "with frames and a navigation tree" 를 추천한다.
           아무튼, 지원하는 문서 형식은 HTML / PDF(LaTeX) / RTF(word) / Manpage(Linux help) / XML 이다.


Step 4. Diagram 탭
           이녀석은 다른 작업을 해야 하는지 모르겠지만, GraphViz 는 별도의 패키지를 깔아야 하고
           built-in은 독립적으로 생성이 가능하다는 차이가 있다.(결과물은 당연히 GraphViz가 좋을듯?)


Step 5. Run
           솔찍히.. Next만 죽어라 누르다가 계속 누르면 만들어 지겠지.. 했는데 안만들어져서 한참을
           찾다보니 겨우겨우 "Run doxygen" 이라는 버튼이 발견되었다. ㄱ-
           아무튼 설정을 다하고 Run 버튼을 누르면 문서 생성이 시작된다.


[링크 : http://www.stack.nl/~dimitri/doxygen/] doxygen 공식 홈페이지
[링크 : http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc] 다운로드 링크
[링크 : http://www.graphviz.org/Download_windows.php] 그래프 그려주는 plugin(?)

[링크 : http://jwmx.tistory.com/1496]

신고

'프로그램 사용 > doxygen' 카테고리의 다른 글

doxygen  (0) 2015.11.09
doxygen - 부제 : 독한녀석!  (0) 2010.03.26
Posted by 구차니
TAG DoxyGen

댓글을 달아 주세요