คัดลอกมาจาก: 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>nantNAnt 0.91 (Build 0.91.3801.0; alpha1; 5/29/2010)Copyright (C) 2001-2010 Gerry Shawhttp://nant.sourceforge.netBuildfile: file:///G:/blogging content/ndoc/NDocTaskDemo/NDoc.buildTarget 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 SUCCEEDEDTotal time: 7.9 seconds.G:\blogging content\ndoc\NDocTaskDemo>
- เข้าไปใน folder ที่กำหนดไว้ให้สร้าง XML document file ขึ้นมา จะมี file ชื่อ NDocTaskDemo.chm
- เปิด NDocTaskDemo.chm ขึ้นมา จะมีคำอธิบาย class และ method ที่เราได้เขียน comement ไว้