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

เมื่อ : 21-Jul-11 21:36 อ่าน : 235 ครั้ง
Tag : c# nant

ในภาษา 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 อธิบายคลาส, พรอพเพอร์ตี และเมธอดที่เราได้สร้างขึ้น

 /// 
    /// main class of program
    /// 
    class Program
    {
        /// 
        /// entry point of application and print message "Hello World" to screen
        /// 
        ///command line arguments
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World");
        }
    }

ติดตั้ง NAnt และสร้าง build file ขึ้นมาให้ชื่อว่า ndoc.build ใน ndoc.build เขียนมี script ของ ndoc task ดังนี้

<!--?xml version="1.0" encoding="utf-8" ?-->
<project name="ndoc">
    
    <ndoc>
        
        <assemblies basedir="NDocTaskDemo\bin\Debug">
            <include name="NDocTaskDemo.exe">
        </include></assemblies>
        
        <summaries>
            <include name="NDocTaskDemo.xml">
        </include></summaries>

        <documenters>
            <documenter name="MSDN">

                <property name="OutputDirectory" value="documents">

                <property name="HtmlHelpName" value="NDocTaskDemo">

                <property name="ShowMissingSummaries" value="True">

                <property name="HtmlHelpCompilerFilename" value="hhc.exe">

                <property name="IncludeFavorites" value="False">

                <property name="Title" value="MySystem (NDoc)">

                <property name="SplitTOCs" value="False">

                <property name="DefaulTOC" value="">

                <property name="ShowVisualBasic" value="False">

                <property name="ShowMissingSummaries" value="True">

                <property name="ShowMissingRemarks" value="False">

                <property name="ShowMissingParams" value="True">

                <property name="ShowMissingReturns" value="True">

                <property name="ShowMissingValues" value="True">

                <property name="DocumentInternals" value="True">

                <property name="DocumentProtected" value="True">

                <property name="DocumentPrivates" value="True">

                <property name="DocumentEmptyNamespaces" value="False">

                <property name="IncludeAssemblyVersion" value="True">

                <property name="CopyrightText" value="Copyright - CodeSanook.com">

                <property name="CopyrightHref" value="http://www.codesanook.com">
             </documenter>
        </documenters>

    </ndoc>
    
</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 ไว้

download source code ตัวอย่าง

ASP.NET MVC, C#, MonoTouch, Entity Framework, Unit Test ...

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

ความเห็น

Friends