Home

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

Sun, 02/12/2012 - 20:29 — jack

ในภาษา 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 ไว้
 

Ref: codesanook.com