Tài liệu XML cho không gian tên

Question

Bạn có viết xml-doc cho không gian tên không? Và nếu có, làm thế nào và ở đâu?

Tôi nghĩ rằng, nếu có thể, có lẽ một tập tin gần như trống rỗng như thế này:

/// <summary> 
/// This namespace contains stuff 
/// </summary> 
namespace Some.Namespace 
{ 

} 

Nhưng sẽ làm việc đó? Vì bạn ... "khai báo", hoặc ít nhất là sử dụng không gian tên trong tất cả các tệp khác ... và điều gì sẽ xảy ra nếu bạn viết một tài liệu xml ở một nơi khác trên cùng một không gian tên? Một người có thể biến mất không? Hoặc họ sẽ được sáp nhập bằng cách nào đó?

Answer 1

NDoc hỗ trợ này bằng cách nhận một NamespaceDoc lớp học đặc biệt nằm trong mỗi không gian tên, và sử dụng tài liệu từ đó. Tôi đã không thử nó, nhưng Sandcastle xuất hiện để hỗ trợ các trick tương tự.

Edit: Ví dụ:

namespace Some.Namespace 
{ 
    /// <summary> 
    /// This namespace contains stuff 
    /// </summary> 
    public static class NamespaceDoc 
    { 
    } 
} 

Answer 2

Không thể đặt nhận xét về không gian tên.

UseNamespaceDocSummaries on http://ndoc.sourceforge.net/content/documenters.htm

Answer 3

Sandcastle không hỗ trợ NamespaceDoc trực tiếp, nhưng nếu bạn sử dụng Sandcastle Help File Builder bạn có thể sử dụng lớp NamespaceDoc đề cập bởi Tim.

namespace Example 
{ 
    /// <summary> 
    /// <para> 
    ///  Summary 
    /// </para> 
    /// </summary> 
    /// <include file='_Namespace.xml' path='Documentation/*' /> 
    internal class NamespaceDoc 
    { 
    } 
} 

SCHB cũng mở rộng cú pháp một chút và cho phép nhúng mã ví dụ trực tiếp từ tệp mã. Một ví dụ _Namespace.xml:

<?xml version="1.0" encoding="utf-8" ?> 
<Documentation> 
    <summary> 
    <h1 class="heading">Example Namespace</h1> 
    <para> 
     This namespace is used in the following way: 
    </para> 

    <code source="Examples\Class.cs" lang="cs"></code> 
    <code source="Examples\Class.vb" lang="vbnet"></code> 

    <para> 
     Hopefully this helps! 
    </para> 
    </summary> 
</Documentation> 

Bao gồm tài liệu trong tập tin XML cho phép bạn viết tóm tắt ngắn gọn trong mã và mô tả lớn hơn trong một tập tin XML riêng biệt cho các tập tin trợ giúp. Bằng cách này, mã không lộn xộn với tất cả các chi tiết và vẫn dễ đọc.

Answer 4

Nếu sử dụng Mono 's mdoc hệ thống tài liệu, bạn có thể lập tài liệu thành viên không gian tên bằng cách chỉnh sửa tệp tài liệu ns - *. Xml.

Xem mdoc file format documentation để biết thêm chi tiết.

Answer 5

Trình tạo tệp trợ giúp Sandcastle hỗ trợ nhận xét về không gian tên. Mở dự án Sandcastle của bạn. Trong cửa sổ Project Properties, hãy điều hướng đến Summaries và nhấp vào nút Edit Namespace Summaries.

Answer 6

Bạn có thể làm điều đó trong doxygen sử dụng:

/// <summary> 
/// description 
/// </summary> 
namespace name{}; 

Ngoài ra, đó là một thực hành tốt để khai báo không gian tên của bạn trong một tập tin NameSpaces.cs, và bình luận họ chỉ trong tập tin này.