[코드 주석 문서화하자]

우엉 코드 주석 문서화 컴파일 작업 한 번 하려는데 이렇게 힘들 줄이야! 피눈물 쥘쥘입니다...

일단 =ㅅ=) 코드 주석 문서화에 필요한 모든 유틸들을 최신버전으로 받는 것이 좋습니다.
최신버전들끼리 호환이 되고 있기 때문에 직접 프로그램을 제공하는 사이트를 찾아서 다운로드 받는 것이 제일 현명합니다.

이제부터 차근차근 프로그램들을 설치해보아요.

 주의 사항 : 설치 폴더는 항상 C:\Programfiles\로 설정하세요.



1. HTML Help Workshop 설치
HTML Help Workshop 다운로드

위의 경로를 따라 다운로드 페이지에 가셔서 "Download Htmlhelp.exe"를 클릭하셔서 설치파일을 저장하고 설치하도록 하세요.

위의 사진처럼 핑크색으로 박스쳐진 부분을 클릭하시면 됩니다. ^-^)v


2. SandCastle 설치
SandCastle 다운로드

위의 경로를 따라 다운로드 페이지에 가셔서 우측의 "Download"라고 쓰여진 녹색 버튼을 클릭하셔서 설치파일을 저장하고 설치하도록 하세요.
(구 버전의 SandCastle은 언어 속성 중에 Korea가 없을 수도 있으므로, 확인해주세요. 최신 버전은 이미 한국어가 추가되어 있어 따로 설정이 필요없습니다.)


3. SandCastle Help File Builder 설치
SandCastle Help File Builder 다운로드

위의 경로를 따라 다운로드 페이지에 가셔서 우측의 "Download"라고 쓰여진 녹색 버튼을 클릭하셔서 설치파일을 저장하고 설치하도록 하세요.

여기까지 하셨다면 .chm포맷으로 Help file을 생성하는 필요 프로그램들이 준비된 것입니다.

이제 SHFB가 설치된 폴더로 가셔서 "SandcastleBuilderGUI.exe" 를 실행하신 후, 몇 가지 설정들을 해주시면 됩니다.
프로그램이 시작되면 프로젝트를 생성하신 후, "Project Properties"에서 설정들을 수정해주세요.

위의 사진에서처럼 핑크색 박스로 쳐진 탭을 확인하시면 됩니다.

Help file을 .chm형식으로 내보내고 싶은 경우 아래처럼 HelpFileFormat을 HtmlHelp1으로 설정하시면 됩니다.

언어를 한국어로 조정해주시고, VisualStudio2005나 2008버전을 사용하시는 분들은 PresentationStyle을 vs2005로 설정해주시면 됩니다.

임의대로 결과물 출력 경로를 설정해주고 싶은 경우 아래처럼 OutputPath를 본인 마음대로 설정하시면 됩니다.

자! 이제 ProjectProperties 설정은 마쳤습니다. ^ㅁ^)/
이제 우측으로 시선을 돌려주세요!

Project Explorer에 Help file을 뽑아내기 위한 희생양을 추가시킬 시간이 왔습니다.

"Documentation Source"를 우클릭하시면 파일 열기 다이얼로그가 뜨는데요.
유심히 Open file format을 살펴봐주세요.

.dll과 .xml뿐만 아니라 .exe, .sln, .csproj까지 제공합니다!
우왕ㅋ굳ㅋ 구버전에는 없었던지라 이런 서비스까지도 감격에 빠지게 만드네요.
일일이 참조 .dll들을 넣어주는 작업들이 여간 귀찮은 일이 아니었거든요.

.sln을 넣어주면 해결된다는 사실은 매우 감격스런 일이라는 것을 다시 한 번 말씀드려봅니다.

물론 System.Winodws등의 프로젝트 외부에서 제공하는 .dll파일들은 직접 파일을 찾아서 "References"에 추가해주셔야 합니다.


응헝헝헝응앵으아아앙...
이제사 코드 주석 문서화 작업을 시작할 모든 준비가 갖추어졌습니다. ㅠ_ㅠ...

이제 빌드를 시켜주시면 "Build Output"탭이 생기면서 빌드를 시작합니다.
빌드 로그들이 꽈득 채워지는 모습을 보며 흐믓한 표정을 지으시고 계시겠지만, 곧 모니터를 보며 멍한 표정을 짓게 되실 겁니다.
굉 - 장 - 히 오랜 시간동안 빌드가 될 테니까요...
빌드가 되고 있을동안 다른 작업이나 휴식을 가지시는 것이 좋습니다.

오랜시간 견딘 끝에 빌드 완료 메시지가 뜨면 OutputPath로 가셔서 결과물을 확인해보세요!
이쁘장하게 .chm파일이 당신을 향해 미소짓고 있을 것입니다!

요런 눈망울로?

이제 다른 형식으로 Help file 결과물을 만들어보도록 하겠습니다.
.HxS포맷인데요.

이 형식으로 결과물을 만들기 위해선 또 다시 필요한 기능을 설치해야 합니다.

4. Visual Studio 2008 SDK 1.1 설치
Visual Studio 2008 SDK 1.1 다운로드

.chm을 위해서 필요한 것이 HTML Help Workshop이라면, .HxS를 위해서 Visual Studio 2008 SDK 1.1를 설치해 주셔야 합니다.

설치를 다 하셨다면, 다시 SHFB를 실행하셔서 .chm을 생성했을 때와 같은 방식으로 빌드해주시면 됩니다.

단!
"Project Properties"에서 "HelpFileFormat"을 "MSHelp2"로 변경하신 다음에 말입니다.

비교적으로 .chm때보다 .HxS를 생성하기 위한 빌드 시간이 짧은 편입니다.
행복하죠.

.chm은 프로젝트가 크면 클 수록 빌드 시간이 경악스러우니까요.

빌드를 완료한 후, 결과물 폴더를 향해 빠르게 이동하셨겠지만 .HxS파일을 읽을 수가 없습니다. 엉엉앙앙으해해해흐애애앵 ㅠ_ㅠ...
생성한 .HxS파일을 읽기 위해서 Viewer를 다운로드 받으셔야 합니다.

5. H2Viewer 다운로드
H2Viewer 다운로드

위의 사진에 나와있는 "H2Viewer146.zip"을 다운받아 원하는 위치에 압축을 푸시고, "H2Viewer.exe"를 실행하신 후, 적절한 네임스페이스를 선택하시면 아래처럼 실행화면이 뜹니다.

상단에 있는 file탭에서 파일 열기를 클릭하셔서 .HxS파일을 여시면 원하는 결과물을 보실 수 있습니다. ^ㅁ^)/

응어어어어헝헝헝헝 험난한 코드 주석 문서화 작업을 이제 모두 마쳤습니다.

참고로 .chm파일로 배출하시다가 빌드 오류가 발생되면 저처럼 포기하시고 .HxS로 Output하시는 것도 하나의 방법이겠습니다. ㅠ_ㅠ)...

그럼, 이것으로 포스팅을 마칠게요우!
수고하셨습니다! >ㅅ<)/



추신 : Sandcastle을 사용한 간단 문서화 라 하여 공도님의 블로그에도 Sandcastle을 이용한 문서화 방법에 대해 포스팅이 되어있는데요, DocProject라는 것을 설치하여 VisualStudio에서 직접 문서화를 실행할 수 있는 Proejct Template을 제공합니다. 다만, English Only라는 점... 그것도 모르고 설치하고 왜 안되나 끙끙대다 피눈물 쏟았네요.