간만에 API 문서 만들려고 하니까
SandCastle이 바뀐 부분들도 많고 신경 쓸 포인트도 있는듯하여
정리하는 차원에서 포스팅합니다.
1. XML 주석 작성
/// < 눌러서 나오는 놈들만 작성하자. 아래와 같은 author를 입력해도 사용되지 않는다.
/// <author>Kimstar</author>
2. 접근 제한자
public 으로 된 놈들만 문서화 대상이다.
외부로 노출하지 않을 놈들은 internal로 하던가..
예를 들어, 스마트 태그를 위해 DesignerActionList 를 상속받은 놈들은 굳이 API 문서화 할 필요가 없다.
3. 패치 적용
마지막 패치를 다운받아 설치된 sandcastle 폴더에 덮어써라. 기존버전에서는 enum 주석 작성시 오류가 있다.
4. 궁합
SHFB(Sandcastle Help File Builder)와 SandCastle 버전이 맞아야 된다.
5. NamespaceDoc
Namespace용 주석을 위해서는 아래를 참조하여 작성하라.
http://www.ewoodruff.us/shfbdocs/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm
안 그러면 아래와 같은 오류가 발생한다.
[Missing <summary> documentation for "T:Inticube.Framework.Form1"]Inticube.Framework.Common.StopWatch를 위한 NamespaceDoc 예제는 아래와 같다
namespace Inticube.Framework.Common.StopWatch
{
/// <summary>
/// These are the namespace comments for <c>Inticube.Framework.Common.Test</c>.<br/>
/// 움하하하하하<br/>
/// 히히히히히
/// </summary>
[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
class NamespaceDoc { }
}6. 설치파일
- http://sandcastle.codeplex.com/
- http://shfb.codeplex.com/
- http://sandcastlestyles.codeplex.com/ (마지막 패치를 적용할것)
7. 참고
- http://kimstar.pe.kr/blog/166
- http://blog.jayway.com/2010/08/28/get-your-sandcastle-up-and-running-within-15-minutes/
- http://happyyhj.blog.me/114319431
8. 잘못된 주석
주석이 잘못되면 아래와 같이 XML에 오류가 표시된다.
SHFB로 컴파일하기 전에 오류가 없는지 확인하라.
<!-- 잘못된 형식의 XML 주석은 "P:XXX.YYY" 멤버에 대해 무시됩니다. -->9. 특수문자 조심
주석에서 사용할 수 없는 특수문자가 포함될 경우 오류가 발생한다.
예를 들어 <> 같은 놈들은 <> 요렇게 표시해야 한다.
Visual Studio 에디터에서 보면 잘못된 부분은
주석색깔(녹색)이 아니고 잘못되었다는 물결표시가 있음을 알 수 있다.
10. New Line
줄을 띄어쓰고 싶으면 <br/>를 사용한다.
예외적으로 <code></code>에서는 자동으로 개행되므로 <br/>를 사용하지 않는다.
/// 이렇게
/// 쓴다고 줄이 띄어지지 않는다./// 이렇게 써야<br/>
/// 줄이 띄어진다.11. 예제
첨부한 예제의 사용환경은 아래와 같습니다.
- visual studio 2010, c# 4.0
- Sandcastle Help File Builder Utilities, version 1.9.1.0
- MrefBuilder (v2.6.10621.1)
- XslTransform (v2.6.10621.1)
