Dịch: Sử dụng cú pháp Markdown trong nhận xét Javadoc

Sử dụng Cú pháp Markdown trong Nhận xét Javadoc

Trong bài đăng này, chúng ta sẽ xem xét cách bạn có thể viết nhận xét Javadoc bằng Markdown thay vì cú pháp Javadoc tiêu chuẩn. Vậy Markdown là gì? Markdown là một ngôn ngữ đánh dấu đơn giản có thể tùy ý dịch sang HTML bằng công cụ cùng tên. Markdown được sử dụng rộng rãi để định dạng các tệp readme, khi viết bài đăng trên diễn đàn và trong trình soạn thảo văn bản để nhanh chóng tạo ra các tài liệu văn bản đẹp mắt. (Wikipedia: Markdown ) Văn bản được định dạng trong Markdown rất dễ đọc. Nhiều loại Markdown khác nhau được sử dụng trên Stack Overflow hoặc GitHub để định dạng nội dung do người dùng tạo.

Cài đặt

Theo mặc định, công cụ Javadoc sử dụng các nhận xét Javadoc để tạo tài liệu API dưới dạng HTML. Quá trình này có thể được cấu hình lại bằng Doclets . Doclets là các chương trình Java xác định nội dung và định dạng tệp đầu ra của công cụ Javadoc. Markdown-doclet thay thế Java Doclet tiêu chuẩn và do đó cung cấp cho nhà phát triển khả năng sử dụng cú pháp Markdown trong các nhận xét Javadoc của họ. Bạn có thể cài đặt nó trong Maven bằng maven-javadoc-plugin. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Viết bình luận trong Markdown

Bây giờ bạn có thể sử dụng cú pháp Markdown để viết bình luận Javadoc: /** * ## Large headline * ### Smaller headline * * This is a comment that contains `code` parts. * * Code blocks: * * ```java * int foo = 42; * System.out.println(foo); * ``` * * Quote blocks: * * > This is a block quote * * lists: * * - first item * - second item * - third item * * This is a text that contains an [external link][link]. * * [link]: http://external-link.com/ * * @param id the user id * @return the user object with the passed `id` or `null` if no user with this `id` is found */ public User findUser(long id) { ... } Sau khi thực thi

mvn javadoc:Javadoc

tài liệu API HTML được tạo được đặt tại

mục tiêu/trang web/apidocs.

Tài liệu được tạo cho đoạn mã trên trông như thế này: Như bạn có thể thấy trong hình, các nhận xét Javadoc được chuyển đổi hoàn hảo sang HTML.

Phần kết luận

Markdown có một lợi thế rõ ràng so với cú pháp Javadoc tiêu chuẩn: nó dễ đọc mã nguồn hơn nhiều. Chỉ cần xem qua một số nhận xét về phương pháp trong java.util.Map: nhiều trong số đó chứa đầy các thẻ định dạng và khó đọc nếu không sử dụng các công cụ bổ sung. Nhưng bạn cần nhớ rằng Markdown có thể gây ra sự cố với các công cụ và IDE chỉ có thể hoạt động với cú pháp Javadoc tiêu chuẩn. Nguồn: Sử dụng cú pháp Markdown trong nhận xét Javadoc từ đối tác JCG của chúng tôi , Michael Scharhag, từ blog mscharhag, Lập trình và Nội dung.