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

Question

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

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

Một vấn đề khác là việc sử dụng 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 các dự án lớn khó điều hướng bằng tìm kiếm nhanh của Firefox.

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

lý thuyết câu hỏi:
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 đó chuẩn ?
EDIT:A useful link to Sun' wiki on this topic.

Answer 1

Có doclet docBook. DocBook là loại tài liệu phong phú hơn (X) HTML và tốt hơn cho việc 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.

Answer 2

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, các khái niệm này bắt nguồn từ những năm trước đây trong một sản phẩm có tên doxygen, mà 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ó một cái nhìn về môi trường lập trình được sử dụng bởi Donald Knuth để tạo ra TeX (Literate programming).

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 đó, việc trình bày 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 công cụ JavaDoc hỗ trợ. Bạn có thể cung cấp một trình cắm (như chúng tôi) 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, mọi người đều 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 gốc.

Answer 3

Để trả lời câu hỏi thực tế của bạn, tôi đã googled 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à rất "Web-oh-twoeye" nhưng ít nhất là bạn được bảo đảm làm việc trong một môi trường ngoại tuyến, và nó đủ nhỏ để gửi cùng với API của bạn. tôi loại bỏ việc sử dụng các khung hình, 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 khi đọc, diễn giải và tạo ra nó.

Answer 4

Bạn có thể muốn cụm từ theo cách ít gây hấn và hách. Hầu hết mọi người không quan tâm đến tài nguyên kỹ thuật trông như thế nào và "Không đủ Web 2.0!" nghe giống như marketroidspeak.

Và chính xác thì bạn sẽ xem xét "có thể sử dụng được nhiều hơn"? Cá nhân, tôi chắc chắn sẽ thích 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ể có thể giúp với những người đó.

Vâng, điều tốt đẹp về JavaDoc là nó trái ngược 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 doclet để tạo loại tài liệu API bạn muốn?

Tại sao không ai khác đã làm điều đó cho đến nay (có vẻ như là trường hợp) là dự đ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.

Answer 5

Cá nhân tôi vẫn thấy Javadoc rất hữu ích. Đặc biệt vì nó được chuẩn hóa. Tôi không biết về bất kỳ phong cách 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 kinh khủng để sử dụng, chẳng hạn).

Để tìm kiếm: Sử dụng Javadoc Search Frame, việc này giúp việc sử dụng Javadoc dễ dàng hơn rất nhiều. Nó có sẵn dưới dạng Userscript for Firefox và dưới dạng Google Chrome Extension.

Answer 6

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 trong số đó là nó rất đơ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 tôi nếu tôi muốn! Trong khi tôi đồng ý rằng một chút đổi mới có thể theo thứ tự và đặc biệt là JDK là một nỗi đau để duyệt qua, tôi sẽ không dám phát minh lại bánh xe hoàn toàn 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ỉ là về bất cứ đâu.

Answer 7

Gần đây tôi đã nhận được thư chuyển tiếp mà 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ải tiến đối với javadoc/doclet cho JDK7. Trang wiki 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 tân trang lại. Các ảnh chụp màn hình thiết kế mới được tải lên wiki dự án. Đầu ra javadoc đánh dấu sẽ được sửa đổi thành HTML và WCAG 2.0 hợp lệ.

Vì vậy, chắc chắn vẫn còn hoạt động đang diễn ra ở đó, ngay cả khi hơi muộn. Tuy nhiên, trong mắt tôi, một trong những hạn chế lớn nhất của Javadoc là sự kết nối rất chặt chẽ với HTML. Nhiều lớp có Javadoc bao gồm HTML theo ngữ cảnh 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 tự do đưa vào bất cứ thứ gì họ muốn trong HTML ở đó 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 của điều này, t và không thể thay đổi và do đó vẫn còn.

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

Answer 8

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

Ví dụ: Đánh dấu, như được sử dụng ở đây, sẽ tuyệt vời, có thể đọc được ở 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 mức độ có thể.Tôi chắc rằng mọi người đã duyệt qua JavaDoc trực tuyến của API vốn không được tài liệu hoặc hầu như không được ghi chép và do đó khó sử dụng hơn mức cần thiết.

Điều này không được các trình cải cách mã (ví dụ, trong Eclipse, hoặc có thể khi nguồn cam kết) phá hủy hoàn toàn bất kỳ cấu trúc có thể đọc nào mà bạn có thể đặt trong một nhận xét JavaDoc (ví dụ, danh sách các mục) thành một blob của văn bản, trừ khi bạn theo nghĩa đen sử dụng hai vận chuyển trở về nơi bạn muốn sử dụng một).

Answer 9

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

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

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à các trường, chỉ mục ngữ nghĩa của các lớp và các gói, phân biệt các phương thức tĩnh, nhà máy, không được chấp nhận từ 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. và hơn thế nữa.

Triển vọng tổng thể cho JDK 7 là pretty grim.

Answer 10

Tôi đã tạo một Markdown (java) Doclet sẽ lấy ý kiến ​​nguồn trong văn bản được định dạng Markdown và tạo cùng một Javadocs HTML.

Tài liệu mới cũng thực hiện một số phần khôi phục trên văn bản, nhưng HTML được tạo không thay đổi ở giai đoạn này.

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

Answer 11

Một thông minh seachable javadoc viewer:

Đối với nhiều lần, tôi phải đối mặt với vấn đề duyệt javadoc. Tôi đã tìm kiếm một cái 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 thì giải pháp là ở đây.

1. Cài đặt plugin GreaseMonkey, trang web tùy chỉnh của nó 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 học) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

2. Để dầu mỡ hoạt động, chúng tôi cần một số tập lệnh người dùng để tùy chỉnh. Điều này có thể được tải xuống bởi greasemonkey tự động. Cài đặt usercript từ JavaDoc search frame hoặc JavaDoc incremental search.

Điều này phù hợp với tôi.

Answer 12

JavaDoc tự nó cực kỳ linh hoạt vì bạn có thể thay thế doclet chuẩn bằng một doclet tùy chỉnh để cung cấp một cái gì đó đáp ứng các nhu cầu cụ thể của dự án của bạn. Về dự án tôi đã làm việc, chúng tôi đã tạo ra 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 ra dữ liệu JavaDoc trong XML, điều này đã sử dụng các thẻ để đảm bảo thậm chí đánh dấu HTML trong các nhận xét mã cũng được tạo thành. 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 cách sử dụng ứng dụng một trang (tương tự như công cụ máy tính để bàn), nhưng tất cả từ bên trong trình duyệt - không có bất kỳ mã/cơ sở hạ tầng phía máy chủ nào. Người xem bao gồm các tính năng tiêu chuẩn như tìm kiếm, định vị cây, vv

Dưới đây là một liên kết đến một điểm vào mẫu trong tài liệu khá lớn: JavaDoc viewer sample

Dưới đây là một hình ảnh cũng: