สร้าง MSDN style document (.chm) จาก XML comment ง่าย ๆ ด้วย NAnt และ NDoc Task

คัดลอกมาจาก: codesanook.com

ในภาษา C# เราสามารถที่จะทำการ Comment เนื้อหาบางส่วนของโปรแกรม เพื่อไม่ให้ compiler นำไปแปลความหมาย ซึ่งจะมีประโยชน์ดังนี้

  • เขียนคำอธิบายการทำงานของคำสั่งที่เขียนขึ้น
  • เก็บส่วนที่ยังทำงานไม่ได้หรือยังไม่สมบูรณ์ไว้ โดยไม่ให้ compiler นำไปแปลความหมาย

ลักษณะการ Comment ของ C# แบ่งได้เป็น

  • Single Line Comment  Ex.
    // this is comment
  • Block Comment Ex.
    /*this is block
    comment */
  • XML Comment  Ex.
         /// <summary>
        /// This is comment.
        /// </summary>
จุดที่น่าสนใจก็คือ หากเรา comment class, property หรือ method ในแบบ XML เราสามารถใช้ NDoc สร้าง document file ในรูปแบบ MSDN-style HTML Help (.chm) ขึ้นมาได้ สำหรับเป็นคู่มืออธิบายการใช้งาน (help file) ของคลาสหรือคำสั่งอื่นๆ ภายในโปรแกรม  ช่วยให้นักพัฒนาโปรแกรม (developer) คนอื่นในทีมเข้าใจการใช้งานคลาสที่เราเขียนขึ้น และนำไปใช้งานต่อได้
ขั้นตอนการสร้าง XML document file
  • สร้าง comment อธิบายคลาส, พรอพเพอร์ตี และเมธอดที่เราได้สร้างขึ้น
    01 /// <summary>
    02    /// main class of program
    03    /// </summary>
    04    class Program
    05    {
    06        /// <summary>
    07        /// entry point of application and print message "Hello World" to screen
    08        /// </summary>
    09        ///<param name="args">command line arguments
    10        static void Main(string[] args)
    11        {
    12            Console.WriteLine("Hello World");
    13        }
    14    }      
  • ติดตั้ง NAnt และสร้าง build file ขึ้นมาให้ชื่อว่า ndoc.build ใน ndoc.build เขียนมี script ของ ndoc task ดังนี้
    01 <!--?xml version="1.0" encoding="utf-8" ?-->
    02 <project name="ndoc">
    03     
    04     <ndoc>
    05         
    06         <assemblies basedir="NDocTaskDemo\bin\Debug">
    07             <include name="NDocTaskDemo.exe">
    08         </include></assemblies>
    09         
    10         <summaries>
    11             <include name="NDocTaskDemo.xml">
    12         </include></summaries>
    13
    14         <documenters>
    15             <documenter name="MSDN">
    16
    17                 <property name="OutputDirectory" value="documents">
    18
    19                 <property name="HtmlHelpName" value="NDocTaskDemo">
    20
    21                 <property name="ShowMissingSummaries" value="True">
    22
    23                 <property name="HtmlHelpCompilerFilename"value="hhc.exe">
    24
    25                 <property name="IncludeFavorites" value="False">
    26
    27                 <property name="Title" value="MySystem (NDoc)">
    28
    29                 <property name="SplitTOCs" value="False">
    30
    31                 <property name="DefaulTOC" value="">
    32
    33                 <property name="ShowVisualBasic" value="False">
    34
    35                 <property name="ShowMissingSummaries" value="True">
    36
    37                 <property name="ShowMissingRemarks" value="False">
    38
    39                 <property name="ShowMissingParams" value="True">
    40
    41                 <property name="ShowMissingReturns" value="True">
    42
    43                 <property name="ShowMissingValues" value="True">
    44
    45                 <property name="DocumentInternals" value="True">
    46
    47                 <property name="DocumentProtected" value="True">
    48
    49                 <property name="DocumentPrivates" value="True">
    50
    51                 <property name="DocumentEmptyNamespaces"value="False">
    52
    53                 <property name="IncludeAssemblyVersion"value="True">
    54
    55                 <property name="CopyrightText" value="Copyright - CodeSanook.com">
    56
    57                 <property name="CopyrightHref"value="http://www.codesanook.com">
    58              </documenter>
    59         </documenters>
    60
    61     </ndoc>
    62     
    63 </project>

     

  • เปิด command prompt ในตำแหน่งที่เก็บ project.build เรียกใช้งาน build file นี้ด้วยคำสั่ง nant จะมีผลลัพธ์แสดงที่หน้าจอดังนี้
    G:\blogging content\ndoc\NDocTaskDemo>nant
    NAnt 0.91 (Build 0.91.3801.0; alpha1; 5/29/2010)
    Copyright (C) 2001-2010 Gerry Shaw
    http://nant.sourceforge.net
    Buildfile: file:///G:/blogging content/ndoc/NDocTaskDemo/NDoc.build
    Target framework: Microsoft .NET Framework 4.0
         [ndoc] Initializing…
         [ndoc] Merging XML documentation…
         [ndoc] Building file mapping…
         [ndoc] Loading XSLT files…
         [ndoc] Generating HTML pages…
         [ndoc] Generating HTML content file…
         [ndoc] Compiling HTML Help file…
         [ndoc] Done.
    BUILD SUCCEEDED
    Total time: 7.9 seconds.
    G:\blogging content\ndoc\NDocTaskDemo>
  • เข้าไปใน folder ที่กำหนดไว้ให้สร้าง XML document file ขึ้นมา จะมี file ชื่อ NDocTaskDemo.chm
  • เปิด NDocTaskDemo.chm ขึ้นมา จะมีคำอธิบาย class และ method ที่เราได้เขียน comement ไว้