Visual Studio với DoxyGen cho tài liệu, hoặc chúng ta nên sử dụng cái gì khác?

Question

Chúng tôi hiện đang sử dụng DoxyGen để viết mã bằng C/C++, PHP và Java. Để có một môi trường nhất quán, thật tuyệt khi sử dụng nó cho tài liệu C#.

Tuy nhiên chúng tôi đang tự hỏi:

• Bạn có thấy bất kỳ lợi thế trong cách bố trí tài liệu được tạo ra hoặc cấu trúc sử dụng một cái gì đó khác hơn doxygen? Chúng tôi đang tạo tài liệu cho các nhà phát triển bên ngoài có kinh nghiệm với C# và nền tảng .NET. Có lẽ chúng được sử dụng cho một định dạng tài liệu nhất định?
• DoxyGen tích hợp tốt với Visual Studio như thế nào? Có cái gì đó cho phép một thế hệ tài liệu một cú nhấp chuột từ bên trong IDE?
• Một số hệ thống tài liệu khác có được tích hợp nhiều hơn với Visual Studio không?

Answer 1

Cách mặc định để ghi lại mã C# trong Visual Studio là XML documentation comments.Theo tôi đây là cách tốt nhất để đi cho mã C# bởi vì hỗ trợ cho điều này đã được tích hợp trong Visual Studio (thẻ bình luận tự động hoàn thành, cảnh báo về các thông số bị thiếu hoặc sai chính tả, ...). Để ghi lại một phương pháp, chỉ cần gõ ba dấu gạch chéo (///) ở phía trước của cơ thể phương pháp, và Visual Studio sẽ chèn một mẫu comment trống để bạn có thể điền vào, như vậy:

/// <summary> 
/// 
/// </summary> 
/// <param name="bar"></param> 
private void Foo(int bar) 
{ 
    // ... 
} 

Bạn có thể cấu hình Visual Studio để tạo ra một tệp XML từ tất cả các nhận xét, sau đó sẽ được đưa vào trình tạo tài liệu như Sandcastle. Nếu bạn muốn sử dụng Doxygen, điều này không có vấn đề gì vì nó hỗ trợ phân tích các nhận xét XML.

Để tổng hợp: Tôi khuyên bạn nên sử dụng nhận xét XML về nhận xét Doxygen đặc biệt cho mã C#. Bằng cách này bạn có tất cả các tùy chọn. Bạn có thể tạo tài liệu theo cách bố trí Doxygen tiêu chuẩn mà tổ chức của bạn quen thuộc (vì Doxygen hỗ trợ nhận xét XML) cộng với bạn có tùy chọn tạo tài liệu theo định dạng được các nhà phát triển .NET biết đến (với Sandcastle và Sandcastle Help FileBuilder).

Ah, và cũng cố gắng GhostDoc ...

Answer 2

Visual Studio không có hệ thống tài liệu tích hợp.

Nếu bạn muốn nhất quán với các ngôn ngữ khác, bạn có thể thử sử dụng Doxygen với Doxycomment Addin cho Visual Studio.

Đối với tài liệu C# hoặc .NET, một số công cụ tồn tại và được sử dụng nhiều nhất (theo kiến ​​thức của tôi) là Sandcastle.

Cuối cùng, bạn có thể kiểm tra điều này blog entry cung cấp một tập lệnh Python nhỏ có thể chuyển đổi một số thẻ C# cụ thể thành thẻ Doxygen.

Answer 3

Có một số tùy chọn cho tài liệu:

• Microsoft cách miễn phí. Sử dụng các bình luận tài liệu DocXml, và sau đó là Sandcastle hoặc một công cụ tương tự để xây dựng tài liệu kiểu MSDN. Ưu điểm của điều này là Visual Studio nhận ra tài liệu (nó có màu cú pháp các chú thích) và tài liệu được hệ thống Intellisense chọn ngay lập tức (vì vậy nếu bạn di chuột qua phương thức bạn đang gọi, chú giải công cụ sẽ hiển thị thông tin tóm tắt và tham số mà bạn đã nhập trong Chú thích tài liệu)

• Hệ thống Doxygen miễn phí. Điều này dễ sử dụng hơn và linh hoạt hơn, nhưng không được hỗ trợ bởi Visual Studio, vì vậy bạn sẽ mất các ưu điểm tô màu và intellisense. Về phía cộng, Doxygen phân tích cú pháp định dạng DocXml, vì vậy bạn có thể tận dụng tối đa cả hai thế giới bằng cách sử dụng định dạng DocXml với Doxygen để tạo ra sự trợ giúp từ bên ngoài.

• Các sản phẩm thương mại như DocumentX, cho phép bạn chỉnh sửa tài liệu trong cửa sổ WYSIWYG.

Tôi muốn giới thiệu bắt đầu với DocXml ý kiến ​​và Doxygen để tạo ra sự giúp đỡ từ bên ngoài, vì đó là cách rẻ nhất và dễ nhất để bắt đầu, và giữ lại tất cả những tính năng tốt nhất của Visual Studio (IntelliSense vv).

Tôi cũng khuyên bạn nên xem bổ trợ của mình, Atomineer Pro Documentation, giúp tạo và cập nhật các nhận xét định dạng DocXml, Doxygen, Qt hoặc JavaDoc nhanh hơn và dễ dàng hơn trong VS - một bổ sung lý tưởng cho cả Doxygen và Sandcastle .

Answer 4

NET phát triển được sử dụng để định dạng tài liệu MSDN giống như được sử dụng trong VS giúp đỡ. Tốt nhất là tích hợp trực tiếp trong VS giúp vì nó cung cấp một số tính năng tiền thưởng như trợ giúp F1, bộ lọc, Index thống nhất và TOC. Một số công cụ đã được đề cập. Tôi sẽ thêm một giải pháp thương mại một cú nhấp chuột, VSdocman.

Nhận xét tài liệu XML rất tuyệt vì chúng được sử dụng tự động trong IntelliSense và Thông tin nhanh về trình duyệt đối tượng.

Answer 5

Doxygen có thể tiêu thụ nhận xét của C# doc (///) tốt. Ghi lại mã của bạn như bình thường và chạy doxygen để quét chúng thành các tệp html, chm và pdf độc lập. Đây là cách tiếp cận đa năng, đơn giản và không xâm lấn nhất.

Trong khi doxygen không được tích hợp vào phòng thu trực quan, nó đi kèm với một IDE đơn giản và có thể viết kịch bản như một công cụ tùy chỉnh bên ngoài. Cá nhân, tôi đã tích hợp doxygen vào các kịch bản xây dựng của mình và nó hoạt động hoàn hảo.

Cuối cùng, doxygen là nền tảng đa nền tảng (đây là một lợi thế nếu bạn cần phải chuyển sang Mono) và nhanh hơn đáng kể so với SandCastle (cả để thiết lập và chạy).

Đây là một ví dụ về sản lượng doxygen cho C# mã trên một dự án ~ 1Mloc: http://www.opentk.com/files/doc/annotated.html