Tài liệu không gian tên trên dự án .Net (Sandcastle)?

Question

Tôi bắt đầu sử dụng Sandcastle một số thời gian trước đây để tạo Trang web Tài liệu cho một trong các dự án của chúng tôi. Nó hoạt động khá tốt nhưng chúng tôi luôn chỉ viết tài liệu cho các lớp, phương thức, thuộc tính (...) trong dự án của chúng tôi và có tài liệu hoàn toàn riêng cho dự án tổng thể và các phần/mô-đun/không gian tên dự án. Nó sẽ là tốt đẹp nếu tôi có thể kết hợp tài liệu đó với nhau và thêm tài liệu tương ứng cho các tập tin trợ giúp được tạo ra nhưng tôi không thể tìm ra cách để làm điều đó.

Chỉ cần thêm ý kiến ​​để khai báo không gian tên dường như không làm việc (C#):

/// <summary> 
/// My short namespace description 
/// </summary> 
namespace MyNamespace { ... } 

Có ai biết làm thế nào để làm điều này? Tôi biết nó có thể bằng cách nào đó và nó sẽ thực sự tốt đẹp để có ... :)

Answer 1

Sandcastle cũng hỗ trợ các tài liệu ndoc kiểu namespace, cho phép bạn để dính tài liệu trong các file nguồn:

Đơn giản chỉ cần tạo ra một lớp ngoài công lập được gọi là NamespaceDoc trong không gian tên bạn muốn ghi lại, và xml chú thích doc cho lớp đó sẽ được sử dụng cho không gian tên.

Tô điểm cho nó bằng thuộc tính [CompilerGenerated] để ngăn chính lớp hiển thị trong tài liệu.

Ví dụ:

namespace Some.Test 
{ 
    /// <summary> 
    /// The <see cref="Some.Test"/> namespace contains classes for .... 
    /// </summary> 

    [System.Runtime.CompilerServices.CompilerGenerated] 
    class NamespaceDoc 
    { 
    } 
} 

Các hạng mục công trình trong SandCastle nằm here.

Answer 2

Nếu bạn sử dụng Sandcastle Help File Builder có một hộp thoại để nhập tóm tắt Không gian tên. (Rõ ràng cũng hỗ trợ cho việc xác định một lớp học cụ thể, nhưng tôi sẽ không thích nó ..)

Từ danh sách tính năng:

Định nghĩa của bản tóm tắt dự án và namespace bình luận tóm tắt mà sẽ xuất hiện trong tập tin trợ giúp. Bạn cũng có thể dễ dàng chỉ ra không gian tên nào để bao gồm hoặc loại trừ khỏi tệp trợ giúp. Hỗ trợ cũng được bao gồm trong việc chỉ định nhận xét không gian tên qua lớp Không gian tênDoc trong mỗi không gian tên .

Answer 3

Sử dụng Sandcastle Help File Builder. Nó cho phép để xác định giới thiệu không gian tên trong hồ sơ dự án XML

Ví dụ:

<namespaceSummaryItem name="System" isDocumented="True"> 
    Generic interfaces and helper classes. 
</namespaceSummaryItem> 

Tài liệu tham khảo:

• example of Open Source project mà tạo ra tài liệu với mọi xây dựng (tất cả các kịch bản đang trong thân cây ).
• Đó là how the documentation by SHFB looks like on the Web (nó được triển khai trên tất cả buộc phải xây dựng)

.

Answer 4

Bạn không thể thêm tài liệu tham khảo như vậy - làm điều đó thông qua NamespaceDoc.cs trường

tức

/// <summary> /// Concrete implementation of see cref="IInterface" using see cref="Concrete"
/// </summary> class NamespaceDoc { }

see here

Answer 5

Tôi biết đó là một bài đăng cũ, nhưng điều này có thể giúp ích cho người khác.

Following this link, bạn có thể đặt mô tả cho không gian tên mà không cần thêm lớp không công khai vào dự án của bạn.

Để chỉnh sửa tóm tắt không gian tên, hãy mở rộng phần tóm tắt trong tab Thuộc tính dự án trong SHFB. Bạn sẽ thấy một cài đặt có tên là "NamespaceSummaries", ban đầu hiển thị giá trị, "(Không có)". Nhấp vào cài đặt để chọn nó và một nút hiển thị biểu tượng dấu ba chấm (...) sẽ xuất hiện. Nhấn vào nút này để hiển thị hộp thoại Namespace Tóm tắt, hình dưới đây:

Answer 6

tôi thấy tài liệu cho một "XML bên ngoài Comments Files". Hiển thị một giản đồ như:

<doc> 
    <assembly/> 
    <members> 
     <member/> 
    </members> 
</doc> 

Nếu điều này được đặt trong một tệp riêng biệt, phần mở rộng sẽ là gì (xml/aml) và có thể sử dụng trong dự án Visual Studio?