Tài liệu bên ngoài của dll với lâu đài cát

Question

Tôi hiện đang phát triển một ứng dụng, yêu cầu dll bên ngoài mà tôi không kiểm soát. Tôi muốn thêm tài liệu cho các lớp này, để những người khác có thể hiểu tại sao tôi thực hiện một số cuộc gọi nhất định mà tôi đang thực hiện cho các tệp DLL bên ngoài này.

Việc thêm các tệp DLL bên ngoài vào nguồn tài liệu thực sự ghi nhật ký các lớp, nhưng tất cả các tóm tắt và thông tin khác không có sẵn. Có thể ghi lại các tệp này hay không (Tốt nhất là không cần phải dịch ngược/tạo lại assembly như là một dự án), vì vậy tôi có thể tạo tài liệu HTML liên quan với sandcastle?

Tôi đã cố gắng giữ cho thư mục hoạt động của Sandcastles được bật, để xem các tệp .xml (Điều tôi thấy được sao chép từ các dự án khác của tôi) đã được tạo và đặt trong thư mục này chưa. Điều này dường như không phải là trường hợp, không có tập tin được tạo ra, và nó đi thẳng để tạo ra các tập tin html.

Answer 1

Theo như tôi hiểu câu hỏi của bạn về việc tạo tài liệu cho một trường hợp sử dụng DLL bên ngoài tôi thấy hai cách có thể mà bạn có thể đi:

• Add "mất tích" ghi chú cho tất cả các mục của DLL bên ngoài mà bạn có thể muốn tài liệu hoặc/và
• thêm chủ đề khái niệm vào tài liệu chương trình của riêng bạn.

Dự án mẫu của tôi Dự án WindowsApplication2 có dạng để thêm hai giá trị sử dụng PDUNZDLL đơn giản. Dự án trình xây dựng tệp trợ giúp Sandcastle "Documentation1" đã được thêm vào và hai Nguồn tài liệu (ở giai đoạn này không có tệp nhận xét XML, xem ảnh chụp nhanh đầu tiên bên dưới). Bạn biết đấy - một tệp DLL không có tệp nhận xét XML sẽ dẫn đến một bản tóm tắt thiếu màu đỏ.

giải pháp được đề xuất (1):

1. Tạo một bình luận XML tập tin trống như sau và đặt tên nó là sau khi lắp ráp với một phần mở rộng .xml ví dụ PDUNZDLL.xml

   <?xml version="1.0"?> 
   <doc> 
       <assembly> 
       <name>PDUNZDLL</name> 
       </assembly> 
       <members> 
       </members> 
   </doc> 
   

2. Lưu tập tin này vào thư mục ví dụ như gỡ lỗi D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug

3. Nhấp đúp vào "Project Properties" (xem ảnh chụp thứ hai dưới đây)
4. Trong hộp thoại Component Configurations, thêm " Thành phần IntelliSense "cho dự án.
5. Chọn "Thiếu thẻ" và đặt thuộc tính Hiển thị thẻ bị thiếu theo ý thích của bạn. Điều này sẽ buộc xây dựng thêm ghi chú "bị thiếu" cho tất cả các mục mà bạn có thể muốn ghi lại.
6. Tạo dự án và bạn sẽ tìm thấy tệp nhận xét XML mới có tên sau khi lắp ráp trong thư mục đầu ra của dự án, ví dụ: D:\Visual-Studio-2015\Projects\WindowsApplication2\Documentation1\Help
7. Chỉnh sửa các phần tử <member> trong tệp nhận xét XML để thêm nhận xét bạn muốn cho từng thành viên như được hiển thị trong ảnh chụp nhanh thứ hai.

Khi bạn hoàn tất, hãy thay thế tệp giữ chỗ ban đầu của bạn, ví dụ:D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug\PDUNZDLL.xml được tạo từ bản dựng với các nhận xét đã chỉnh sửa của bạn. Xây dựng lại dự án tài liệu của bạn.

Điều này đương nhiên tốn thời gian như bất kỳ trợ giúp nào cho các ứng dụng. Và đó thực sự là nhiệm vụ của nhà phát triển DLL.

giải pháp được đề xuất (2):

Reading giữa các dòng của bạn" ... để những người khác có thể hiểu được lý do tại sao tôi đang làm cho một số cuộc gọi tôi là làm cho những tập tin DLL bên ngoài . " dẫn tôi đến đề xuất thêm tài liệu bổ sung vào chương trình của riêng bạn.

Vì vậy, ý của tôi là thêm các chủ đề khái niệm mô tả cách bạn gọi các tính năng của các tệp DLL bên ngoài.

tôi loại bỏ các DLL dưới "Nguồn tài liệu", thêm một thư mục mới "ExternalDLL", thêm một mục mới Khái niệm và Walkthrough, double-click ContentLayout.content trong Solution Explorer, và đã làm tất cả các bước cho nội dung bố cục, Xây dựng lại dự án tài liệu dẫn đến tệp trợ giúp như được hiển thị trong ảnh chụp nhanh thứ ba bên dưới (xem thông tin cơ bản).

Chúc mừng trợ giúp!