Chú thích XML cho chương trình viết bằng C#

[sunflower]

Mới tham khảo một bài viết khá hay bên ZenSoft về chú thích cho các đoạn code mà chúng ta viết. Giúp chương trình rỏ ràng hơn, dể dàng update hơn khi khối lượng code tăng lên quá lớn. Chú thích XML sẽ mô tả đầy đủ cho lớp hay phương thức như giá trị trả về, mục đích, tài liệu tham khảo, những điều tương tự...

Có 2 loại "Chú Thích" sử dụng với .NET FrameWorks. Loại thông thường nhất là các loại "Chú Thích Dòng" (Bất cứ khi nào bạn sử dụng // với C# để đánh dấu một dòng là Chú Thích.) Loại chú thích này thường được sử dụng để giải thích những gì mà dòng lệnh hiện hành hoặc dòng mã kế tiếp đang thực hiện. Còn loại chú thích thứ 2 chính là chú thích XML. Chú thích này ghi chép tài liệu cho một lớp hoặc phương thức bằng cách sử dụng một phần XML. Ngoài ra, nó còn tạo tài liệu API cho ứng dụng. Sau đây là một ví dụ về các chú thích XML được áp dụng và một phương thức C#.=:

/// <summary>/// This method can spilit a String./// </summary>/// <param name="words"></param>/// <param name="ar"></param> private static void SplitString(string words, ref ArrayList ar){     ...}

Như ta đã thấy trong ví dụ trên, các chú thích XML rất đơn giản - đặt /// trước các lớp, giao diện, phương thức , trường hoặc trước phần khai báo thuộc tính. Visual Studio sẽ tự động tổng kết cơ bản về hàm hoặc phương thức cùng với các tham số đi kèm. Có hơn 20 loại thẻ khác nhau có thể được sử dụng trong các chú thich XML, và được chia làm 2 loại chính.

I. Các Thẻ Chính:

Các Thẻ chính là những thẻ mà bạn sử dụng một cách độc lập với những thẻ khác.

1. <summary>:

Vì nó xuất hiện theo thẻ mặc định, nên có thể nó là thẻ quen nhất trong các loại thẻ. Nó nên được sử dụng để ghi chép mục đích chung nhất của tất cả các phương thức public, thuộc tính và trường của một kiểu.

/// <summary>/// Hàm Đánh dấu một kí tự./// </summary>private string MarkKeyword{ .......}

2. <remarks>:

Thẻ này có ý nghĩa là mô tả một kiểu. Có thể bạn không biết điều này bời vì khi chèn các chú thích XML và trong Visual Studio, nó sẽ chèn thẻ <summary> thay vì chèn thẻ <remarks>. Sự khác biệt không lớn nhưng tài liệu C# đề nghị sử dụng <remarks>. Sau đây là ví dụ về thẻ remarks:

/// <remarks>/// Hàm Đánh dấu một kí tự./// </remarks>private string MarkKeyword{ ........}

3. <value>:

Tương tự như 2 thẻ trên, thẻ <value > mô tả giá trị của một thuộc tính. Nó cũng được sử dụng như các thẻ khác:

/// <value>/// Thuộc tính này số lượng các sách có trong thư viện./// </value>protected int numberOfBooks;

4. <param>:

Thẻ <param> được sử dụng để ghi chép từng tham số của một phương thức. Đây là một trong những chú thích hữu dụng nhát bởi vì đôi khi khó nhận biết mục đích của một tham số chỉ từ tên của nó.

/// <summary>/// Hàm này để chia một ArrayList thành chuỗi string./// </summary>/// <param name="words"></param>/// <param name="ar">một danh sách các chủ đề của bài viết.</param>private static void SplitString(string words, ref ArrayList ar){..........}

5. <returns> :

Thẻ này được sử dụng để định nghĩa kiểu trả về của một phương thức. Từ chữ ký của phương thức, bạn biết kiểu nào nó trả về. Do đó, việc khai báo kiểu giá trị cho nó là vô ích mà hãy giải thích những gì mà giá trị trả về đó.

/// <summary>/// Thay thế các ký tự đặc biệt bằng dấu cách/// </summary>/// <param name="s"></param>/// <returns>Giá trị trả lại là những dấu cách</returns>private static string ReplaceSpecialChar(string s){string specialChar = @"'-%*";// Chuỗi ký tự đặc biệt........return s;}

6. <exception> :

Được sử dụng để xác định các ngoại lệ mà một kiểu có thể đưa ra. Thẻ này sử dụng một thuộc tính được gọi là cref. Thuộc tính cref được sử dụng để tham chiếu một kiểu khác. Bằng cách sử dụng thẻ <exception>, bạn nên ghi chép tất cả những ngoại lệ cụ thể mà phương thức có thể đưa ra bằng thuộc tính cref và sau đó giải thích khi nào ngoại lệ có thể được đưa ra.

/// <exception cref="Exception">/// Có lỗi trong quá trình xử lý/// </exception>void Page_LoadComplete(object sender, EventArgs e){........}

Vậy biết những ngoại lệ nào mà một phương thức có thể đưa ra rất quan trọng đối với việc phát triển các ứng dụng chất lượng cao. Vì .NET không cho bạn xác định những ngoại lệ nào mà phương thức có thể đưa ra trong chữ ký phương thức.

7.<example> :

Với thẻ này, có thể được sử dụng để cung cấp một ví dụ về cách sử dụng phương thức, thuộc tính hoặc trường. các ví dụ là một phần chính của việc ghi chép tài liệu chất lượng cao và không có gì có thể hướng dẫn tốt hơn cho các nhà phát triển cách làm việc với các kiểu của bạn. Bằng cách sử dụng thẻ <example> cùng với thẻ <code> (một trong những thẻ thứ cấp), bạn có thể cung cấp trực tiếp các vi dụ mã trong mã của bạn.

/// <summary>/// Thay thế các ký tự đặc biệt bằng dấu cách/// </summary>/// <param name="s"></param>/// <returns></returns>/// <example>/// <code>////// // Chuỗi ký tự đặc biệt////// string specialChar = @"'-%*";////// // gán các ký tự đặc biệt thành ký tự rỗng.////// s = s.Replace(specialChar[i], ' ');////// </code>/// </example>private static string ReplaceSpecialChar(string s)

Bạn nghĩ sao nếu tài liệu MSDN không có các ví dụ. đó chính mà ví dụ cho sự quan trọng của thẻ <example>.

8.<permission> :

Cho phép bạn xác định ai được phép truy cập kiểu của bạn. Thẻ <permission> cũng có thể chứa thuộc tính cref và hầu như luôn hướng sang System.Security.PermissionSer.

/// <summary>/// Tạo chuỗi tìm kiếm từ một danh sách các từ khóa cần tìm/// </summary>/// <param name="fieldName"></param>/// <param name="keywords"></param>/// <returns></returns>/// <permission cref="System.Security.PermissionSer">////// Private Access////// </permission>private static string BuildSQLQuery(string fieldName, ArrayList keywords)

9. <seealso> :

Có thể được sử dụng để tham chiếu các lớp khác hoặc những tài liệu vốn có để gây sự chú ý với người đọc tài liệu. Thẻ này cũng có chứa thuộc tính cref và bạn có thể tham chiếu các kiểu, phương thức, thuộc tính hoặc trường khác mà người dùng có thể quan tâm đến.

/// <summary>/// Tạo chuỗi tìm kiếm từ một danh sách các từ khóa cần tìm/// </summary>/// <param name="fieldName"></param>/// <param name="keywords"></param>/// <returns></returns>/// <seealso cref="SetSQLQuery"/>private static string BuildSQLQuery(string fieldName, ArrayList keywords)

10. <include> :

Thẻ này khác với các thẻ chính khác bởi vì nó được sử dụng để bao hàm các chú thích XML bên ngoài trái với việc ghi chép tài liệu cho bất cứ thứ gì. Thẻ <include> có thể hữu dụng nếu các chú thích XML trong các file nguồn ngày càng trở nên lớn và vụng về. Để sử dụng thẻ này, bạn sẽ cần phải sử dụng tên file cũng như biểu thức XPath vốn sẽ được sử dụng để đi đến các chú thích của bạn.

/// <include file='XMLLib.xml' /// path='doc/members/member[@name="M:XMLLib.Vehicle.Start"]'/>public virtual void Start()

II. Các thẻ thứ cấp:

Có thể được sử dụng bên trong các thẻ chính. Những thẻ này được sử dụng để đánh dấu và định dạng Text để đưa vào các thẻ chính. Trong ví dụ về thẻ <example> ta cũng đã biết được thẻ <code> rồi.

1. Nhập <c> và <code>:

Các thẻ <c> và <code> đều được sử dụng định nghĩa khi nào một phần Text là mã. Sự khác biệt duy nhất giữa 2 thẻ này là <c> có thể được sử dụng để đánh dấu một điều gì đó là mã nội dòng (jnline) trong một câu khác, trong khi <code> được sử dụng để xác lập toàn bộ một khối Text dưới dạng mã. Có nghĩa là <code> có chứa các ngắt dòng còn <c> thì không.

/// <summary>/// Thay thế các ký tự đặc biệt bằng dấu cách bằng hàm <c>ReplaceSpecialChar("a")</c>/// </summary>/// <param name="s"></param>/// <returns></returns>private static string ReplaceSpecialChar(string s)

Nếu bạn muốn cung cấp một ví dụ hoàn chỉnh, thì dùng thẻ <code> sẽ thích hợp hơn.

/// <summary>/// Thay thế các ký tự đặc biệt bằng dấu cách/// </summary>/// <param name="s"></param>/// <returns></returns>/// <example>/// <code>////// // Chuỗi ký tự đặc biệt////// string specialChar = @"'-%*";////// // gán các ký tự đặc biệt thành ký tự rỗng.////// s = s.Replace(specialChar[i], ' ');////// </code>/// </example>private static string ReplaceSpecialChar(string s)

Cả 2 loại thẻ trên nên được sử dụng bất cứ khi nào bạn đưa mã vào các website của mình

2. <para>:

Được sử dụng để chỉ định một đoạn trong các chú thích. Nếu các chú thích dài, bạn nên ngắt nó thành các đoạn để làm cho việc đọc trở nên dễ dàng hơn.

 /// <summary>/// Trong hàm Page_Load này, ta phải làm các công việc sau:/// <para>/// Kiểm tra bài viết có tồn tại hay không/// và chỉ có những người tạo ra bài viết mới được phép sửa bài/// và xem bài viết đó đã được xuất bản chưa?/// Nếu chưa sản xuất thì chỉ có người duyệt bài mới được xem/// </para>/// </summary>/// <param name="sender"></param>/// <param name="e"></param>protected void Page_Load(object sender, EventArgs e)

3. <paramref > :

Có thể được sử dụng để tạo một tham chiếu dẫn sang một tham số. Khi mô tả một phương thức, bạn sẽ thường tham một tham số của phương thức. Bằng cách sử dụng thẻ này, công cụ tạo tài liệu có thể xác định tham số nào mà bạn tham chiếu sang và tạo một link giữa 2 tham số trong một tài liệu

/// <summary>/// hàm tách các ArrayList thành các chuỗi <paramref name="words"/>/// </summary>/// <param name="words"></param>/// <param name="ar"></param>///private static void SplitString(string words, ref ArrayList ar)

4. <see> :

Thẻ <see> có thể được sử dụng giống như thẻ <seealso> ngoại trừ bạn sử dụng <see> trong ngữ cảnh của một thẻ khác. Khi bạn muốn liệt kê một số phương thức mà một lớp chứa và sử dụng thẻ <see> để tham chiếu đến những phương thức đó.

/// <remarks>/// hàm này có nhiều phương thức như <see cref="GetArticlesByFilter"/>GetArticlesByFilter/// and <see cref="UpdatePublish"/>/// </remarks>public class ArticlesDAO

5. Các thẻ List :

Loại thẻ cuối cùng là các thẻ List. Những thẻ này được tạo để sử dụng các List (danh sách). Thẻ <list> được sử dụng để tạo một List và có một thuộc tính gọi là TYPE. Thuộc tính này định nghĩa loại List nào mà bạn đang tạo; giá trị này có thể được thiết lập sang Bullet, number hoặc table. Thẻ <listheader> sau đó có thể được sử dụng để định nghĩa header (Tiêu đề) cho List. Nó có thể chứa các thẻ <term> và <description>. Sau thẻ <listheader>, thẻ <list> có thể chứa bất kỳ số thẻ <item>. Mỗi thẻ <item> tượng trưng cho một mục trong danh sách và có thể bao gồm các thẻ <term> và thẻ <description>. Mỗi mục sẽ luôn chứa một thẻ <description> , nhưng sẽ cần phải chứa thẻ <term> nếu bạn tạo một danh sách định nghĩa.

Sau đây là một ví dụ về danh sách không định nghĩa:

/// <summary>/// <remarks>/// hàm tương tác vói CSDL của đối tượng Article./// <list>///        <listheader><description>Phương Thức</description></listheader>///        <item><description>GetArticlesByFilter</description></item>///        <item><description>UpdatePublish</description></item>///        <item><description>GetArticlesDynamic</description></item>/// </list>/// </remarks>/// </summary>public class ArticlesDAO

Còn đây là ví dụ về danh sách định nghĩa:

/// <summary>/// Thay thế các ký tự đặc biệt bằng dấu cách/// </summary>/// <param name="s">chuỗi chứa các ký tự đặc biệt/// <list>///       <listheader>///              <term>Số</term><description>ký tự đặc biệt</description>///       </listheader>///       <item>///               <term>1</term><description>ký tự "-"</description>///        </item>///        <item>///                <term>2</term><description>ký tự "%"</description>///        </item>///        <item>///                 <term>3</term><description>ký tự "*"</description>///        </item>///        <item>///                 <term>4</term><description>ký tự "dấy nháy ' "</description>///        </item>/// </list>/// </param>///private static string ReplaceSpecialChar(string s)

------------------------------
Nguồn: http://zensoft.vn/ShowArticle.aspx?ID=1165

[nhc1987]

Thực ra cái hay của những cái chú thích xml này không hoàn toàn là giúp cho việc hiển thị trong IDE mà cái hay của nó là có thể giúp ta tạo help tự động.

Nếu bạn nào đã từng xài NDoc thì sẽ biết việc này rõ hơn. NDoc dựa vào các chú thích xml để tạo file help, chú ý là tạo help thư viện cho developer chứ không phải help cho end-user.

Theo kinh nghiệm của nhc thì phần lớn ban đầu khi mới biết cái chú thích xml này mọi người rất khoái dùng hàm nào cũng dùng, lớp nào cũng dùng ... Sau đó, cứ làm nhiều mọi người sẽ cảm thấy công việc nó rất là nhàm chán và riết thì ... bỏ luôn . Do đó, nếu muốn auto luôn thì bạn search cái add-in cho VS khá hay là GhostDoc.

Nghiên cứu nhé. Chúc may mắn

[anhtuyenbk]

Mình là người mới dùng nên rất khoái

[duyviet]

Cái này hay ở chổ là chuơng trình đang chạy mà nó hiển thị tóm tắt đở mắc công nhớ chức năng

[thanhhuy191188]

GhostDoc: Tạo tài liệu từ mã nguồn

Trang chủ: http://www.roland-weigelt.de/ghostdoc .Loại dự án: miễn phí.

Với comment (chú thích) dạng XML của C#, việc tạo tài liệu từ mã nguồn trở nên dễ dàng hơn rất nhiều, và có không ít công cụ giúp bạn thực hiện công việc đó. Tuy nhiên, chính việc comment theo định dạng XML chưa chắc đã "thú vị”. GhostDoc sẽ giải phóng bạn khỏi sự "nhàm chán".

Công cụ này cho phép tự động tạo comment theo định dạng XML cho một method từ kiểu, tham số, tên của nó cũng như các thông tin ngữ cảnh khác. Tất cả những việc bạn cần làm là chọn một method cần chú thích, nhấn chuột phải và chọn Document This. Điều tuyệt vời là GhostDoc cho phép bạn thiết lập định dạng Comment và những quy tắc đoán tên kiểu, tham số... cho phù hợp với phong cách viết mã của bạn.

Sau khi cài đặt, GhostDoc sẽ bổ sung thêm vào Menu Tools của VS một Submenu với 2 mục nhỏ hơn: Configure GhostDoc cho phép cấu hình GhostDoc và Document This (đôi khi sẽ disable) sẽ tự động comment cho file .cs hiện tại.

Mặc dù GhostDoc không phải lúc nào cũng làm việc chính xác, nhưng công cụ này rất đáng cho bạn sử dụng.

Hiện phiên bản mới nhất của GhostDoc là 2.1.3, dung lượng 898KB. Có 2 phiên bản dành riêng cho Visual Studio 2005 và 2008, đều hỗ trợ VB (có hạn chế) và Windows Vista. Phiên bản gần nhất dành cho VS 2003 là 1.30, chỉ hỗ trợ C# và không hỗ trợ Vista.

[Paraside]

Có bạn nào biết chú thích sao cho nó hiển thị giống trong Netbean không ?

[ff8711]

Giờ mới đọc nhưng công nhận biết thêm cái này hay thật .Cảm ơn bác Sun