?

단축키

Prev이전 문서

Next다음 문서

+ - Up Down Comment Print
?

단축키

Prev이전 문서

Next다음 문서

+ - Up Down Comment Print

출처 : 여기



C#에서 소스코드에 여러 가지 주석을 달 수 있다. .NET Framework는 소스코드의 문서화에 활용할 수 있도록 다음과 같은 권장 태그를 미리 정의해 두었다.

  • <c>text</c>
    • 설명
      • 태그 사이에 있는 텍스트를 코드로 나타낸다. 여러 줄을 한꺼번에 코드로 나타내려면 <code>태그를 이용한다.
  • 매개변수
    • text : 코드로 나타낼 텍스트
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// text for class TestClass
      public class TestClass
      {
          /// <summary><c>DoWork</c> is a method in the <c>TestClass</c> class.
          /// </summary>
          public static void DoWork(int Int1)
          {
          }

          /// text for Main
          static void Main()
          {
          }
      }
  • <code>content</code>
    • 설명
      • 여러 줄을 코드로 표시할 때 사용한다. <c> 태그는 설명에 있는 텍스트를 코드로 표시하는 데 사용한다.
  • 매개변수
    • content : 코드로 표시할 한 줄 또는 그 이상의 텍스트
  • 예제
    • <example>의 예제를 참조할 것.
  • <example>description<example>
    • 설명
      • 클래스나 메서드 등에 사용법에 대해 설명하고, <code> 태그를 같이 사용하여 예제 코드를 기술하기도 한다.
  • 매개변수
    • description : 예제 코드에 대한 설명
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// text for class TestClass
      public class TestClass
      {
          
      /// <summary>
          /// The GetZero method.
          /// </summary>
          /// <example> This sample shows how to call the GetZero method.
          /// <code>
          /// class TestClass 
          /// {
          ///     static int Main() 
          ///     {
          ///         return GetZero();
          ///     }
          /// }
          /// </code>
          /// </example>
          public static int GetZero()
          {
              
      return 0;
          }

          
      /// text for Main
          static void Main()
          {
          }
      }
  • <exception cref="member">description</exception>
    • 설명
      • 메서드, 속성, 이벤트 및 인덱서에 대해 <exception> 태그를 사용하여 발생가능한 예외(exception)를 기술한다. "cref" 참조는 <see cref="member">를 이용하여 정의할 수 있다.
  • 매개변수
    • cref="member" : member는 현재 컴파일 환경에 있는 예외에 대한 참조를 나타낸다. 컴파일시 컴파일러는 이 예외가 존재하는지 확인하여 출력 XML의 정식이름으로 변환한다.
    • description : 예외에 대한 설명
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// comment for class
      public class EClass : System.Exception
      {
          // class definition...
      }

      /// comment for class
      class TestClass
      {
          /// <exception cref="System.Exception">Thrown when...</exception>
          public void DoSomething()
          {
              try
              {
              }
              catch (EClass)
              {
              }
          }
      }
  • <include file='filename' path='tagpath[@name="id"]' />
    • 설명
      • 다른 파일에 있는 주석을 참조할 수 있도록 한다. 이 기능을 이용하면 소스코드파일과 주석파일을 따로 관리할 수 있다.
  • 매개변수
    • filename : 주석을 포함하고 있는 문서파일 이름
    • tagpath : name태그를 찾을 수 있는 filename의 태그 경로
    • name : 주석 앞에 오는 태그의 이름 지정자
    • id : 주석 앞에 오는 태그의 ID
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
      class
       Test
      {
          static void Main()
          {
          }
      }

      /// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
      class Test2
      {
          public void Test()
          {
          }
      }

    • xml_include_tag.doc 파일

    • <MyDocs>

      <MyMembers name="test">
      <summary>
      The summary for this type.
      </summary>
      </MyMembers>

      <MyMembers name="test2">
      <summary>
      The summary for this other type.
      </summary>
      </MyMembers>

      </MyDocs>
  • <list type="bullet" | "number" | "table">
    <listheader>
    <term>term</term>
    <description>description</description>
    </listheader>
    <item>
    <term>term</term>
    <description>description</description>
    </item>
    </list>
    • 설명
      • 소스코드를 설명할 때 어떤 내용을 목록으로 나타내고 싶은 경우에는 <list>태그를 사용한다. type을 다르게 지정하여 목록을 다른 형태로 보이도록 하는데 활용할 수 있다.
      • <listheader>태그는 정의 목록 또는 테이블의 헤더를 정의하는데 이용한다. <listheader> 블록은 <term>과 <description>을 가질 수 있는데, 정의 목록인 경우에는 <term>과 <description>을 모두 지정해 주어야 하지만, 테이블을 정의 할 때는 <term>만 지정하면 된다.
      • <term>태그는 <description>태그에서 정의할 용어를 기술한다.
      • <description>태그는 <tag>태그에서 기술한 용어에 대한 정의를 기술한다.
      • <item>태그에는 목록의 항목을 기술한다. <item> 블록 역시 <listheader>와 마찬가지로 <term>과 <description>을 가질 수 있는데, 정의 목록이 아닌 경우에는 description만 지정하면 된다.
  • 매개변수
    • term : description에서 정의할 용어
    • description : term에 대한 정의 또는 목록으로 나타낼 개별 항목의 내용
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// text for class TestClass
      public class TestClass
      {
          /// <summary>Here is an example of a bulleted list:
          /// <list type="bullet">
          /// <item>
          /// <description>Item 1.</description>
          /// </item>
          /// <item>
          /// <description>Item 2.</description>
          /// </item>
          /// </list>
          /// </summary>
          static void Main()
          {
          }
      }
  • <para>content</para>
    • 설명
      • 단락을 나타내는 태그로 <summary>, <remarks> 또는 <returns>와 같은 태그 블럭 내에서 단락을 구분하기 위해 사용된다.
  • 매개변수
    • content : 단락으로 구분하여 나타낼 텍스트
  • 예제
    • <summary>태그의 예제를 참조할 것.
  • <param name='name'>description</param>
    • 설명
      • 매개변수를 설명하기 위한 태그로 메서드의 매개변수 중 하나를 설명하기 위해서는 메서드 선언부의 주석에 <param> 태그를 사용해야 한다.
      • <param> 태그의 텍스트는 IntelliSense, 개체 브라우저 및 코드 주석 웹 보고서에 표시된다.
  • 매개변수
    • description : 매개변수에 대한 설명
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// text for class TestClass
      public class TestClass
      {
          /// <param name="Int1">Used to indicate status.</param>
          public static void DoWork(int Int1)
          {
          }
          /// text for Main
          static void Main()
          {
          }
      }
  • <paramref name="name"/>
    • 설명
      • 코드 주석에 포함되어 있는 어떤 단어를 지정하는데 사용한다. 예를 들어, <summary>나 <remarks>와 같은 설명적인 태그 블럭에 포함되어 있는 매개변수를 같은 블럭에 포함되어 있는 다른 텍스트와는 다른 스타일로 나타내도록 할 때 사용할 수 있다.
  • 매개변수
    • name : 참조할 매개변수 명
  • 예제
    • // compile with: /doc:DocFileName.xml 
      
      /// text for class TestClass
      public class TestClass
      {
          /// <summary>DoWork is a method in the TestClass class.  
          /// The <paramref name="Int1"/> parameter takes a number.
          /// </summary>
          public static void DoWork(int Int1)
          {
          }
      
          /// text for Main
          static void Main()
          {
          }
      }
  • <permission cref="member">description</permission>
    • 설명
      • <permission> 태그는 member에 대한 access를 문서화할 수 있도록 해준다. System.Security.PermissionSet클래스를 이용하여 어떤 멤버에 대한 access를 지정(명시)할 수 있다.
  • 매개변수
    • cref="member" : 현재 컴파일 환경에서 호출될 수 있는 멤버 또는 필드에 대한 참조이다. 컴파일러는 지정된 코드 요소가 존재하고 출력 XML에서member를 정식 요소 이름으로 변환할 수 있는지 확인한다.
  • 예제
    • // compile with: /doc:DocFileName.xml 

      class TestClass
      {
          /// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission>
          public static void Test()
          {
          }

          static void Main()
          {
          }
      }
  • <remarks>description</remarks>
    • 설명
      • <remarks>태그는 어떤 형식에 대한 추가적인 정보로 사용되어, <summary>에 명시된 정보를 보충한다.
      • <remarks> 태그의 텍스트는 개체 브라우저 및 코드 주석 웹 보고서에 표시된다.
  • 매개변수
    • description : 멤버에 대한 설명
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// <summary>
      /// You may have some primary information about this class.
      /// </summary>
      /// <remarks>
      /// You may have some additional information about this class.
      /// </remarks>
      public class TestClass
      {
          /// text for Main
          static void Main()
          {
          }
      }
  • <returns>description</returns>
    • 설명
      • 메서드의 반환값을 설명한다. 메서드의 반환값을 설명하기 위해서는 메서드 선언부의 주석에 <returns>태그가 사용되어야 한다.
  • 매개변수
    • description : 반환값에 대한 설명
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// <summary>
      /// You may have some primary information about this class.
      /// </summary>
      /// <remarks>
      /// You may have some additional information about this class.
      /// </remarks>
      public class TestClass
      {
          /// text for Main
          static void Main()
          {
          }
      }
  • <see cref="member"/>
    • 설명
      • 태그를 사용하면 텍스트 내부에서 링크를 지정할 수 있다. 참고 항목 부분에 배치할 텍스트를 지정하려면 <seealso>를 사용한다.
  • 매개변수
    • cref="member" : member는 현재 컴파일 환경에서 호출될 수 있는 멤버 또는 필드에 대한 참조이다. 컴파일러는 지정된 코드 요소가 있고 출력 XML의 요소 이름에 member가 전달되는지 검사한다.
  • 예제
    • <see> 사용 예제는 <summary> 예제를 참조할 것.
    • 다음은 제네릭 형식에 대한 cref참조를 만드는 예제이다.
    • // compile with: /doc:DocFileName.xml 

      // the following cref shows how to specify the reference, such that,
      // the compiler will resolve the reference
      /// <summary cref="C{T}">
      /// </summary>
      class
       A { }

      // the following cref shows another way to specify the reference, 
      // such that, the compiler will resolve the reference
      // <summary cref="C &lt; T &gt;">

      // the following cref shows how to hard-code the reference
      /// <summary cref="T:C`1">
      /// </summary>
      class B { }

      /// <summary cref="A">
      /// </summary>
      /// <typeparam name="T"></typeparam>
      class C<T> { }
  • <seealso cref="member"/>
    • 설명
      • <seealso> 태그를 사용하면 참고 항목 부분에 나타나는 텍스트를 지정할 수 있다. 텍스트 내부에서 링크를 지정하려면 <see>를 사용한다.
  • 매개변수
    • cref="member": member는 현재 컴파일 환경에서 호출될 수 있는 멤버 또는 필드에 대한 참조이다. 컴파일러는 지정된 코드 요소가 존재하고 출력 XML에서 member를 요소 이름에 전달하는지 확인한다.
  • 예제
    • <summary>의 예제를 참조할 것

  • <summary>description</summary>
    • 설명
      • 형식 또는 형식 멤버를 설명하려면 <summary> 태그를 사용해야 한다.

      • 형식에 대한 설명을 보충하는 정보를 추가하려면 <remarks>를 사용한다.

      • IntelliSense에 나타나는 형식에 대한 정보는 <summary> 태그에 기술된 내용만 나타나며, 개체 브라우저 및 코드 주석 웹 보고서에도 표시된다.

  • 매개변수
    • description : 형식 또는 형식 멤버에 대한 요약설명
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// text for class TestClass
      public
       class TestClass
      {
          
      /// <summary>DoWork is a method in the TestClass class.
          /// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>
          /// <seealso cref="TestClass.Main"/>
          /// </summary>
          public static void DoWork(int Int1)
          {
          }

          
      /// text for Main
          static void Main()
          {
          }
      }
  • <typeparam name="name">description</typeparam>
    • 설명
      • <typeparam>은 형식 매개변수(type parameter)를 설명하기 위한 태그로, 제네릭(generic) 형이나 메서드 선언부의 주석에 사용되어야 한다.
  • 매개변수
    • name : 형식 매개변수 이름
    • description : 형식매개변수에 대한 설명
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// comment for class
      public
       class TestClass
      {
          
      /// <summary>
          /// Creates a new array of arbitrary type <typeparamref name="T"/>
          /// </summary>
          /// <typeparam name="T">The element type of the array</typeparam>
          public static T[] mkArray<T>(int n)
          {
              
      return new T[n];
          }
      }
  • <typeparamref name="name"/>
    • 설명
      • 코드 주석에 포함되어 있는 어떤 단어를 지정하는데 사용한다. 예를 들어, <summary>나 <remarks>와 같은 설명적인 태그 블럭에 포함되어 있는 매개변수를 같은 블럭에 포함되어 있는 다른 텍스트와는 다른 스타일로 나타내도록 할 때 사용할 수 있다.
  • 매개변수
    • description : 반환값에 대한 설명
  • 예제
    • <typeparam>의 예제를 참조할 것.
  • <value>property-description</value>
    • 설명
      • <value> 태그를 사용하여 속성이 나타내는 값을 설명할 수 있다. Visual Studio .NET 개발 환경의 코드 마법사를 통해 속성을 추가하면 새 속성에 대한 <summary>태그도 추가된다. 그러면 사용자는 직접 <value> 태그를 추가하여 속성이 나타내는 값을 설명해야 합니다.
  • 매개변수
    • property-description : 속성에 대한 설명
  • 예제
    • // compile with: /doc:DocFileName.xml 

      /// text for class Employee
      public
       class Employee
      {
          
      private string _name;

          
      /// <summary>The Name property represents the employee's name.</summary>
          /// <value>The Name property gets/sets the _name data member.</value>
          public string Name
          {
              
      get
              {
                  
      return _name;
              }
              
      set
              {
                  _name = value;
              }
          }
      }

      /// text for class MainClass
      public class MainClass
      {
          
      /// text for Main
          static void Main()
          {
          }
      }

    위의 태그를 사용한 XML문서를 지원하는 XSLT(스타일 문서)는 다음 사이트를 참고한다.

    Simple XSLT stylesheet for Visual Studio .NET XML documentation

    By Emma Burrows


    Dreamy의 코드 스크랩

    내가 모으고 내가 보는

    List of Articles
    번호 분류 제목 날짜 조회 수 추천 수
    47 C# C# 자주 쓰는 코드 2012.12.10 11949 0
    46 C# SmtpClient로 메일 보내기 - gmail 2013.01.18 12287 0
    45 C# C#에서 명령줄 인수(command line argument) 사용하기 2016.01.04 12420 0
    44 C# INI 파일 대신에 XML 로 설정값 저장/유지 하기 2014.04.03 12434 0
    43 C# 변경된 파일을 감시하는 루틴 2013.10.30 12507 0
    42 C# C# 배열 array 2014.10.22 12572 0
    41 C# 텍스트 파일에서 읽기/쓰기 2013.08.08 12894 0
    40 C# ArrayList를 string[] 배열로 변환하는 방법 2015.09.23 12954 0
    39 C# 트레이 아이콘 만들기 2013.08.05 13157 0
    38 C# Drag & Drop으로 파일받기 구현 1 2012.11.29 14157 0
    » C# C# XML Documentation - C# 소스코드 문서화 [출처] C# XML Documentation - C# 소스코드 문서화 2013.10.01 14636 0
    36 C# AutoResetEvent 클래스 - 신호(Signal)에 의한 쓰레드 동기화 2013.08.14 14725 0
    35 C# TreeView의 rootnode(TreeNode)에서 하위 항목 찾기 2015.09.21 15053 0
    34 C# 에디트 박스 제일 밑으로 스크롤 하기 2012.08.21 15061 0
    33 C# Visual C# 에서 XP 테마 적용하기 2012.05.21 15160 0
    목록
    Board Pagination ‹ Prev 1 2 3 4 5 Next ›
    / 5

    나눔글꼴 설치 안내


    이 PC에는 나눔글꼴이 설치되어 있지 않습니다.

    이 사이트를 나눔글꼴로 보기 위해서는
    나눔글꼴을 설치해야 합니다.

    설치 취소

    Designed by sketchbooks.co.kr / sketchbook5 board skin

    Sketchbook5, 스케치북5

    Sketchbook5, 스케치북5

    Sketchbook5, 스케치북5

    Sketchbook5, 스케치북5