Чи є якісні та сучасні альтернативи Javadoc? [зачинено]

Погодьмося: вам не потрібно бути дизайнером, щоб побачити, що Javadoc за замовчуванням виглядає потворно .

В Інтернеті є деякі ресурси, які пропонують перероблений Javadoc. Але поведінка за замовчуванням представляє продукт і повинна бути настільки розумно красивою.

Іншою проблемою є той факт, що зручність використання Javadoc не є сучасною у порівнянні з іншими подібними ресурсами.

Особливо великими проектами важко орієнтуватися за допомогою швидкого пошуку Firefox.

Практичне запитання:
Чи існують окремі (настільні) програми, які можуть переглядати існуючий Javadoc більш зручним способом, ніж це робить браузер?
Я думаю про щось на зразок браузера документації Mono.

Теоретичне запитання:
Хтось знає, чи є якісь плани щодо розвитку Javadoc, якимось стандартизованим чином?
EDIT: корисне посилання на Sun 'wiki на цю тему .

Я створив Markdown (java) Doclet який буде приймати вихідні коментарі у форматованому текстом Markdown і створювати ті самі HTML Javadocs.

У новому документі також зроблено певний рестайлінг тексту, але згенерований HTML на цьому етапі не змінюється.

Це певним чином вирішує проблеми HTML-in-java-commenting, що, мабуть, є найбільшою проблемою зручності використання в поточному Javadoc.

Я не думаю, що концепції Javadoc застарілі. Наскільки я бачу, ці концепції вкорінені кілька років тому в продукті з назвою доксиген, який досі доступний для інших мов (тобто Objective-C, де він широко використовується). Навіть у цього є свої попередники - погляньте на середовище програмування, яке використовував Дональд Кнут для створення TeX ( Грамотне програмування ).

Тим не менше, це інтригуюча ідея мати єдине джерело програмного коду та документації.

Окрім цього, презентацію документації можна налаштувати під ваші особливі потреби за допомогою плагіна, що підтримується інструментом JavaDoc. Ви можете надати плагін (як і ми), який публікує безпосередньо у базі даних, до якої можна безпосередньо отримати доступ через Інтернет. Використовуючи співпрацю, кожен може надати додаткові коментарі чи роз’яснення до документації, яка може знайти шлях назад до першоджерела.

Javadoc - найкраща система автоматичного формування документації вихідного коду, яку я коли-небудь бачив. Велика частина цього полягає в тому, що це настільки просто - я можу переглядати javadocs навіть за допомогою свого 5-річного стільникового телефону, якщо захочу! Незважаючи на те, що я згоден з тим, що трохи підтяжки обличчя може бути в порядку, і особливо JDK - це проблема, яку потрібно переглядати, я б не наважився повністю винаходити колесо, тому що те, що ми маємо зараз, це РІШНЕ, просте у використанні рішення для своєї мети, яке працює майже де завгодно.

Нещодавно мені надіслали лист про те, що Sun працює над модернізацією виводу Javadoc HTML. З зазначеної пошти:

Ми пропонуємо вдосконалити javadoc / doclet для JDK7. Вікі-сторінка проекту знаходиться за адресою http://wikis.sun.com/display/Javadoc/Home . Як частина запропонованих удосконалень, інтерфейс користувача виводу javadoc буде оновлений. Знімки екрану нового дизайну завантажуються у вікі проекту. Вихідна розмітка javadoc буде змінена, щоб вона відповідала дійсності HTML та WCAG 2.0.

Тож там, безумовно, ще триває робота, навіть якщо дещо запізніла. Однак, на мій погляд, одним з найбільших недоліків Javadoc є його дуже тісна взаємодія з HTML. У багатьох класах є Javadoc, який включає буквальний HTML і також покладається на вихід, який є HTML. На жаль, але це ніколи не зміниться, я думаю. Це все ж означає, що розробники можуть вільно включати туди все, що завгодно, в HTML, що може бути недійсним, неправильно сформованим і т. Д. Тож адаптація результатів роботи інструменту javadoc - це лише одна частина цього, інша виграла ' t і не може змінитися і, таким чином, залишається.

Що стосується перегляду документації, я також вважаю документацію HTML трохи громіздкою. Я зазвичай використовую вигляд Javadoc в Eclipse. У нього також є недоліки (повільний, і ви не можете реально шукати), але для більшості речей це досить добре.

Особисто я все ще вважаю Javadoc дуже корисним. Тим більше, що він стандартизований. Я не знаю жодного основного стилю документації, в якому мені легше орієнтуватися (що цілком може бути суб'єктивним, але особисто мені, наприклад, MSDN страшно користуватися).

Для пошуку: Використовуйте Javadoc Search Frame , це значно полегшує використання Javadoc усіх видів. Він доступний як Userscript для Firefox та як розширення Google Chrome .

Щоб відповісти на ваше практичне запитання, я погуглив і запитав друзів і придумав їх. Forrestdoc, doclet та кисень.

Друге питання, я б сказав, що так, це не дуже "Web-oh-twoeye", але, принаймні, ви гарантовано працюєте в автономному середовищі і досить малі, щоб поставлятися разом із вашим API. Я зневажаю використання фреймів, але тоді це працює досить добре для javadoc. Я не бачив жодних планів змінити це. Eclipse має певну підтримку JavaDoc, що стосується її читання, інтерпретації та генерації.

Можливо, ви захочете сформулювати це менш агресивно і невпевнено. Більшість людей не цікавить, як виглядає технічний ресурс, і "Це недостатньо Web 2.0!" звучить як безтурботна розмова маркетолога.

А що саме ви вважали б "більш корисним"? Особисто я, безумовно, хотів би повнотекстового пошуку та кращого браузера використання, і AJAX міг би допомогти з ними.

Ну, приємним у JavaDoc є те, що він є протилежністю застарілому - він довільно розширюваний. Чому б вам не піти далі і не написати доклет який створює такий документ API, який ви хочете?

Чому ще ніхто цього не робив (що, мабуть, і є), можна здогадуватися - можливо, ніхто інший не відчуває цього так сильно, як ти.

Є документ DocBook. DocBook є більш багатим типом документа, ніж (X) HTML, і краще для опису технічного змісту. З джерела DocBook ви можете генерувати всілякі різні вихідні формати.

Я особисто хотів би більш читабельного стандарту "документації до коментарів", ніж HTML (і, отже, хиткий) JavaDoc.

Наприклад, MarkDown, як він використовується тут, був би чудовим, зручним для читання у джерелі, добре відформатованим зовні джерела.

В даний час JavaDoc, я думаю, багато людей використовують коментарі JavaDoc, але насправді не документують настільки, наскільки могли. Я впевнений, що всі переглядали API JavaDoc в Інтернеті, який не був задокументований або ледве задокументований, і тому набагато складніший у використанні, ніж мав би бути.

Цьому не допомагають переформатувальники коду (наприклад, у Eclipse або, можливо, після коміту джерела), які повністю знищують будь-яку читабельну структуру, яку ви могли б помістити в коментарі JavaDoc (наприклад, список елементів), в одну велику крапку тексту, якщо ви буквально не використовуєте два повернення каретки там, де ви хочете скористатися одним).

Хтось знає, чи є якісь плани щодо розвитку Javadoc якимось стандартизованим способом?

Відповідний JSR (JSR 260), який визначає вдосконалення Javadoc, був відмінений від JDK 7 (на даний момент). Огляд запланованого (з цього сайту ):

Оновіть Javadoc, щоб забезпечити більш багатий набір тегів, щоб забезпечити більш структуровану презентацію документації Javadoc. Цей JSR охоплює: категоризацію методів і полів, семантичний індекс класів і пакетів, розрізнення статичних, заводських, застарілих методів від звичайних методів, розрізнення доступу до властивостей, комбінування та розділення інформації на представлення, вбудовування прикладів та загальних випадків використання, і більше.

Загальний прогноз для JDK 7 досить похмурий .

JavaDoc сам по собі надзвичайно гнучкий, оскільки ви можете замінити стандартний документ на власний, щоб забезпечити щось, що відповідає вашим проектам.

У рамках проекту, над яким я працював, ми створили систему документації на основі HTML / XML (використовуючи клієнтську версію XSLT 2.0 на JS) для нашого продукту з повністю інтегрованою JavaDoc. Для цього був використаний спеціальний документ для створення даних JavaDoc у XML, він використовував тег для забезпечення рівномірної розмітки HTML у коментарях коду.

Завдяки цьому ми змогли забезпечити інтерактивну взаємодію з користувачем на одній сторінці (подібно до інструменту для настільних ПК), але все в браузері - без будь-якого коду / інфраструктури на стороні сервера. Переглядач включав стандартні функції, такі як пошук, навігація по дереву тощо.

Ось посилання на зразок точки входу у досить великій документації: зразок програми перегляду JavaDoc

Ось також зображення:

Розумний прицільний переглядач Javadoc:

Багато разів я стикаюся з проблемою перегляду JavaDoc. Я шукав щось подібне до опції пошуку документів Adnroid. Нарешті я отримую щось подібне. Якщо ви використовуєте Firefox, рішення тут.

1. Встановіть плагін GreaseMonkey, його своєрідну настройку веб-сторінки так, як ми бачимо. (Нам потрібно налаштувати будь-яку сторінку документа Java, щоб ми могли шукати за назвою класу) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

2. Для того, щоб greasemonkey працював, нам потрібен скрипт користувача для налаштування. Це можна завантажити за допомогою програмиsemsemonkey автоматично. Встановіть скрипт користувача з пошукового фрейму JavaDoc або додаткового пошуку JavaDoc .

Для мене це чудово працює.