Có một số lựa chọn thay thế tốt và hiện đại cho Javadoc không? [đóng cửa]

Hãy đối mặt với nó: Bạn không cần phải là một nhà thiết kế để thấy rằng Javadoc mặc định trông xấu xí .

Có một số tài nguyên trên web cung cấp Javadoc được tạo kiểu lại. Tuy nhiên, hành vi mặc định đại diện cho sản phẩm và phải tương đối đẹp mắt.

Một vấn đề khác là khả năng sử dụng của Javadoc không được cập nhật so với các tài nguyên tương tự khác.

Đặc biệt là các dự án lớn rất khó điều hướng bằng tính năng tìm kiếm nhanh của Firefox.

Câu hỏi thực tế:
Có bất kỳ ứng dụng độc lập (máy tính để bàn) nào có thể duyệt qua Javadoc hiện có theo cách dễ sử dụng hơn trình duyệt không?
Tôi đang nghĩ về thứ gì đó giống như trình duyệt tài liệu của Mono.

Câu hỏi lý thuyết:
Có ai biết, nếu có một số kế hoạch phát triển Javadoc, theo một cách nào đó được tiêu chuẩn hóa không?
CHỈNH SỬA: Một liên kết hữu ích đến Sun 'wiki về chủ đề này .

Tôi đã tạo một Tài liệu Markdown (java) sẽ lấy các nhận xét nguồn trong văn bản được định dạng Markdown và tạo cùng một Javadocs HTML.

Doclet mới cũng thực hiện một số thao tác sắp xếp lại văn bản, nhưng HTML được tạo không bị thay đổi ở giai đoạn này.

Đó là một số cách để giải quyết các vấn đề nhận xét HTML-trong-java, đây có lẽ là vấn đề khả năng sử dụng lớn nhất với Javadoc hiện tại.

Tôi không nghĩ rằng các khái niệm về Javadoc đã lỗi thời. Theo như tôi có thể thấy, những khái niệm này được bắt nguồn từ nhiều năm trước trong một sản phẩm có tên doxygen, hiện vẫn có sẵn cho các ngôn ngữ khác (tức là Objective-C, nơi nó được sử dụng nhiều). Ngay cả điều này cũng có những người tiền nhiệm của nó - hãy xem môi trường lập trình được Donald Knuth sử dụng để tạo ra TeX ( Lập trình Literate ).

Tuy nhiên, đó là một ý tưởng hấp dẫn để có một nguồn duy nhất cho mã chương trình và tài liệu.

Bên cạnh đó, bản trình bày của tài liệu có thể được tùy chỉnh theo nhu cầu đặc biệt của bạn bằng cách sử dụng hệ thống trình cắm được hỗ trợ bởi công cụ JavaDoc. Bạn có thể cung cấp một trình cắm thêm (như chúng tôi làm) xuất bản trực tiếp vào cơ sở dữ liệu có thể truy cập trực tiếp qua web. Sử dụng cộng tác, bất kỳ ai cũng có thể cung cấp nhận xét hoặc giải thích bổ sung cho tài liệu có thể tìm đường trở lại nguồn ban đầu.

Javadoc là hệ thống tạo tài liệu tự động mã nguồn tốt nhất mà tôi từng thấy. Phần lớn của điều đó là nó quá đơn giản - tôi có thể duyệt javadocs ngay cả với điện thoại di động 5 tuổi của mình nếu tôi muốn! Mặc dù tôi đồng ý rằng có thể có một chút cải tiến và đặc biệt là JDK rất khó để duyệt qua, tôi sẽ không dám sáng tạo lại hoàn toàn bánh xe bởi vì những gì chúng tôi hiện có là một giải pháp RESTful, dễ sử dụng cho mục đích của nó. chỉ về bất cứ đâu.

Gần đây tôi đã nhận được một thư được chuyển tiếp rằng Sun đang làm việc để hiện đại hóa đầu ra HTML Javadoc. Từ thư đã nói:

Chúng tôi đang đề xuất các cải tiến đối với javadoc / doclet cho JDK7. Trang wiki của dự án được đặt tại http://wikis.sun.com/display/Javadoc/Home . Là một phần của các cải tiến được đề xuất, giao diện người dùng của đầu ra javadoc sẽ được cải tiến. Ảnh chụp màn hình thiết kế mới được tải lên wiki của dự án. Đánh dấu đầu ra javadoc sẽ được sửa đổi để phù hợp với HTML và WCAG 2.0 hợp lệ.

Vì vậy, chắc chắn vẫn có công việc đang diễn ra ở đó, ngay cả khi hơi muộn. Tuy nhiên, trong mắt tôi, một trong những nhược điểm lớn nhất của Javadoc là nó kết hợp rất chặt chẽ với HTML. Nhiều lớp có Javadoc bao gồm HTML theo nghĩa đen và dựa vào đầu ra là HTML. Thật không may, nhưng điều này sẽ không thay đổi bất cứ lúc nào, tôi nghĩ. Tuy nhiên, điều này có nghĩa là các nhà phát triển có thể tự do đưa bất kỳ thứ gì họ muốn vào HTML ở đó, những thứ đó cũng có thể không hợp lệ, không được định dạng tốt, v.v. Vì vậy, việc điều chỉnh đầu ra từ công cụ javadoc chỉ là một phần trong số này, phần còn lại sẽ thắng ' t và không thể thay đổi và do đó vẫn còn.

Đối với tài liệu duyệt, tôi cũng thấy tài liệu HTML hơi khó sử dụng. Tôi thường sử dụng dạng xem Javadoc trong Eclipse. Nó cũng có nhược điểm (chậm và bạn không thể thực sự tìm kiếm) nhưng nó là Good Enough ™ cho hầu hết mọi thứ.

Cá nhân tôi vẫn thấy Javadoc rất hữu ích. Đặc biệt là vì nó được tiêu chuẩn hóa. Tôi không biết bất kỳ kiểu tài liệu chính nào mà tôi thấy dễ điều hướng hơn (điều đó rất có thể là chủ quan, nhưng cá nhân tôi thấy MSDN rất kinh khủng khi sử dụng chẳng hạn).

Đối với việc tìm kiếm: Sử dụng Khung tìm kiếm Javadoc , nó làm cho việc sử dụng Javadoc thuộc mọi loại dễ dàng hơn rất nhiều. Nó có sẵn dưới dạng Bản thảo người dùng cho Firefox và như một Tiện ích mở rộng của Google Chrome .

Để trả lời Câu hỏi thực tế của bạn, tôi đã truy cập vào Google và hỏi bạn bè và đưa ra những điều này. Forrestdoc, doclet và doxygen.

Câu hỏi thứ hai, tôi sẽ nói rằng có, nó không phải là "Web-oh-haieye" nhưng Ít nhất bạn được đảm bảo hoạt động trong môi trường ngoại tuyến và nó đủ nhỏ để vận chuyển cùng với API của bạn. tôi bác bỏ việc sử dụng khung, nhưng sau đó nó hoạt động khá tốt cho javadoc. Tôi đã không thấy bất kỳ kế hoạch để thay đổi nó. Eclipse có một số hỗ trợ cho javadoc về khả năng đọc, thông dịch và tạo nó.

Bạn có thể muốn diễn đạt điều đó theo cách bớt hung hăng và hống hách. Hầu hết mọi người không quan tâm tài nguyên kỹ thuật trông như thế nào, và "Nó không đủ Web 2.0!" nghe có vẻ giống như một phiên bản marketroidspeak.

Và chính xác thì điều gì bạn sẽ coi là "hữu dụng hơn"? Cá nhân tôi chắc chắn muốn tìm kiếm văn bản đầy đủ và một trình duyệt sử dụng tốt hơn, và AJAX có thể giúp được những điều đó.

Chà, điều tốt đẹp về JavaDoc là nó đối lập với lỗi thời - nó có thể mở rộng tùy ý. Tại sao bạn không tiếp tục và viết một doclet tạo ra loại tài liệu API mà bạn muốn?

Tại sao không ai khác làm được điều đó cho đến nay (dường như là trường hợp) là suy đoán của bất kỳ ai - có thể không ai khác cảm thấy mạnh mẽ về nó như bạn.

Có một tập tài liệu DocBook. DocBook là một loại tài liệu phong phú hơn (X) HTML và tốt hơn để mô tả nội dung kỹ thuật. Từ nguồn DocBook, bạn có thể tạo tất cả các loại định dạng đầu ra khác nhau.

Cá nhân tôi muốn có một tiêu chuẩn "tài liệu nhận xét" dễ đọc hơn JavaDoc (và do đó có thể sử dụng thẻ) JavaDoc.

Ví dụ: MarkDown, như được sử dụng ở đây, sẽ rất tuyệt vời, con người có thể đọc được trong nguồn, được định dạng độc đáo bên ngoài nguồn.

Với JavaDoc hiện tại, tôi tưởng tượng nhiều người sử dụng các nhận xét JavaDoc, nhưng không thực sự ghi lại các tài liệu trong phạm vi họ có thể. Tôi chắc rằng mọi người đã duyệt qua JavaDoc trực tuyến của API không được tài liệu hóa hoặc hầu như không được tài liệu hóa và do đó khó sử dụng hơn mức cần thiết.

Điều này không được trợ giúp bởi các bộ định dạng mã (ví dụ: trong Eclipse, hoặc có thể khi cam kết nguồn) phá hủy hoàn toàn bất kỳ cấu trúc nào có thể đọc được mà bạn có thể đã đặt trong nhận xét JavaDoc (ví dụ: danh sách các mục) thành một khối văn bản lớn, trừ khi bạn thực sự sử dụng hai ký tự xuống dòng mà bạn muốn sử dụng).

Có ai biết, nếu có một số kế hoạch phát triển Javadoc, theo một cách nào đó được tiêu chuẩn hóa không?

JSR tương ứng (JSR 260), chỉ định các cải tiến cho Javadoc, đã được bỏ phiếu khỏi JDK 7 (hiện tại). Tổng quan về những gì đã được lên kế hoạch (từ trang web này ):

Nâng cấp Javadoc để cung cấp bộ thẻ phong phú hơn để cho phép trình bày tài liệu Javadoc có cấu trúc hơn. JSR này bao gồm: phân loại các phương thức và trường, chỉ mục ngữ nghĩa của các lớp và gói, phân biệt các phương thức tĩnh, nhà máy, không dùng nữa với các phương thức thông thường, phân biệt các trình truy cập thuộc tính, kết hợp và tách thông tin thành các khung nhìn, nhúng các ví dụ và các trường hợp sử dụng phổ biến, và hơn thế nữa.

Triển vọng tổng thể cho JDK 7 là khá tồi tệ .

Bản thân JavaDoc cực kỳ linh hoạt vì bạn có thể thay thế doclet tiêu chuẩn bằng doclet tùy chỉnh để cung cấp thứ gì đó đáp ứng nhu cầu cụ thể cho các dự án của bạn.

Trong dự án mà tôi đang thực hiện, chúng tôi đã tạo một hệ thống tài liệu dựa trên HTML / XML (sử dụng XSLT 2.0 phía máy khách trên JS) cho sản phẩm của chúng tôi với JavaDoc được tích hợp đầy đủ. Đối với điều này, một doclet tùy chỉnh đã được sử dụng để tạo dữ liệu JavaDoc bằng XML, thẻ tag được sử dụng này để đảm bảo đánh dấu HTML ngay cả trong các chú thích mã cũng được hình thành tốt.

Với điều này, chúng tôi có thể cung cấp trải nghiệm người dùng tương tác bằng ứng dụng một trang (tương tự như công cụ trên máy tính để bàn), nhưng tất cả đều từ bên trong trình duyệt - mà không có bất kỳ mã / cơ sở hạ tầng phía máy chủ nào. Trình xem bao gồm các tính năng tiêu chuẩn như tìm kiếm, điều hướng cây, v.v.

Đây là liên kết đến điểm nhập mẫu trong tài liệu khá rộng lớn: Mẫu trình xem JavaDoc

Đây cũng là một hình ảnh:

Trình xem javadoc thông minh có thể tìm kiếm:

Trong nhiều lần, tôi phải đối mặt với sự cố khi duyệt JavaDoc. Tôi đang tìm kiếm thứ gì đó giống như tùy chọn tìm kiếm tài liệu Adnroid. Cuối cùng tôi nhận được một cái gì đó như thế. Nếu bạn sử dụng firefox, giải pháp là ở đây.

1. Cài đặt plugin GreaseMonkey, loại plugin này tùy chỉnh trang web theo cách chúng ta thấy. (Chúng tôi cần tùy chỉnh bất kỳ trang tài liệu java nào, vì vậy chúng tôi có thể tìm kiếm trên tên lớp) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

2. Để Greasemonkey hoạt động, chúng ta cần một số tập lệnh người dùng để tùy chỉnh. Nó có thể được tải xuống tự động bằng greasemonkey. Cài đặt usercript từ khung tìm kiếm JavaDoc hoặc tìm kiếm gia tăng JavaDoc .

Điều này làm việc tuyệt vời cho tôi.