주석 태그 정리

첨부파일은 솔루션 샘플과 생성된 CHM 파일, sandcastle help builder 프로젝트 파일

invalid-file

참조 문서 : 로컬 MSDN

   

• Summary
  • 형식 또는 형식 멤버를 설명하려면 <summary> 태그를 사용해야 합니다. 형식에 대한 설명을 보충하는 정보를 추가하려면 <remarks>를 사용합니다.
  • IntelliSense에서 <summary> 태그의 텍스트는 형식 정보의 유일한 출처이며, 개체 브라우저에서도 표시됩니다.
• para
  • 단락 텍스트입니다.
  • <para> 태그를 <summary>, <remarks> 또는 <returns> 같은 태그 내에서 사용하여 텍스트에 구문을 추가할 수 있습니다.
  • 실제 내용을 적을때 지금까지는 <br/>로 줄바꿈을 했었는데, 이 태그를 사용하면 굳이 라인끝에 <br/> 태그를 붙이지 않아도 되네요…
• remarks
  • <remarks> 태그는 형식에 대한 정보를 추가하여 <summary>에 지정한 정보를 보충하는 데 사용합니다. 이 정보는 개체 브라우저에 표시됩니다.
  • summary 외의 추가정보를 표시하는 용도
  • 생성된 도움말에 보면 Remarks 로 별도 분리됨
• returns
  • 반환 값을 설명하려면 메서드 선언의 주석에서 <returns> 태그를 사용해야 합니다.
  • void 가 아닌 리턴값이 있는 경우에 사용
• 샘플 소스(코드) 형태로 설명하기 위한 태그들
  • c, code
    • <c> 태그는 설명에 있는 텍스트를 코드로 표시하는 데 사용합니다. 여러 줄을 코드로 표시하려면 <code>를 사용합니다.
  • example
    • <example> 태그를 사용하면 메서드나 기타 라이브러리 멤버의 사용 방법에 대한 예제를 지정할 수 있습니다. 여기에는 일반적으로 <code> 태그가 함께 사용됩니다.
    • 생성된 도움말에 보면 Examples 로 별도 분리됨

    

• 현재 컴파일 환경에서 호출될 수 있는 멤버 또는 필드에 대한 참조
  • see
    <see cref="member" />
    • 주석 중간에 링크를 가진 텍스트를 표시하기 위함
      TestStr 와 같은 프로퍼티 링크를 추가한 예(CHM 파일에 표시되는 스크린 샷)

      

  • seealso
    <seealso cref="member" />
    • 생성된 도움말에 보면 See Also 로 별도 분리됨(링크가 유효한 경우 링크 가짐)
    • 상단의 두 항목은 기본적으로 추가되는 링크이고 세번째 링크가 임의로 추가한 항목임

      

  • 둘다 비슷한 경우인데 seealso 의 경우 도움말 하단에 별도로 나타낼 때 사용하고
    see 의 경우 문장 중간에 특정 단어에 링크를 걸 때 사용하는 듯함
  • <param name="파라메터 명">파라메터 설명</param>, <paramref cref="파라메터 명" />
    파라메터 에 대한 설명 과 파라메터 항목의 링크를 걸 때 사용
  • <typeparam>, <typeparamref> 의 경우는 제네릭과 같은 타입이 지정된 경우 사용
     
• exception
  • 예외를 던지는 경우에 대한 주석
    아래 스크린 샷 처럼 별도 항목으로 표시가 됨
     
  • 
• value
  • 프로퍼티에서 값에 대한 설명
    /// <value>
    /// Get : <see cref="GetButtonTextInvoker" /><br/>
    /// Set : <see cref="SetButtonTextInvoker" /><br/>
    /// </value>
    위 처럼 작성한 경우 아래처럼 별도 항목으로 표시가 됨