Есть ли хорошие и современные альтернативы Джавадоку?

Ответ 1

Я создал Markdown (java) Doclet, который будет принимать исходные комментарии в отформатированном тексте Markdown и создавать те же HTML Javadocs.

Новый doclet также выполняет некоторый рестайлинг в тексте, но сгенерированный HTML на этом этапе не изменяется.

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

Ответ 2

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

Тем не менее, это интригующая идея иметь единственный источник кода программы и документации.

Кроме того, презентация документации может быть настроена под ваши особые потребности с использованием подключаемой системы, поддерживаемой инструментом JavaDoc. Вы можете предоставить подключаемый модуль (как и мы), который публикуется непосредственно в базе данных, которая напрямую доступна через Интернет. Используя сотрудничество, любой может предоставить дополнительные комментарии или пояснения к документации, которая может вернуться к исходному источнику.

Ответ 3

Javadoc - лучшая система генерации автоматической документации исходного кода, которую я когда-либо видел. Большая часть этого заключается в том, что это так просто - я могу просматривать javadocs даже со своим 5-летним сотовым телефоном, если захочу! Хотя я согласен с тем, что немного подтяжка лица может быть в порядке, и особенно JDK - это боль, которую можно просмотреть, я бы не рискнул изобретать колесо полностью, потому что то, что мы имеем в настоящее время, - это простое в использовании решение для своей цели, которое работает почти где угодно.

Ответ 4

Недавно я получил почтовую пересылку, что Sun работает над модернизацией вывода HTML Javadoc. Из указанной почты:

Мы предлагаем улучшения для 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. У этого есть недостатки (медленные, и Вы не можете действительно искать), но это Хорошее Enough ™ для большинства вещей.

Ответ 5

Чтобы ответить на ваш практический вопрос, я погуглил, спросил друзей и придумал их. Forrestdoc, doclet и doxygen.

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

Ответ 6

Лично я до сих пор считаю Джавадока очень полезным. Тем более, что он стандартизирован. Я не знаю какого-либо основного стиля документации, который мне нахожу более удобным для навигации (это может быть очень субъективным, но я лично считаю, что MSDN ужасно использовать, например).

Для поиска: используйте Рамка поиска Javadoc, это делает использование Javadoc всех видов намного проще. Он доступен как UserScript для Firefox и как Расширение Google Chrome.

Ответ 7

Возможно, вы захотите сформулировать это менее агрессивно и властно. Большинство людей не заботятся о том, как выглядит технический ресурс, и "It not Web 2.0 достаточно!" звучит как неистовый marketroidspeak.

И что именно вы считали бы "более пригодным для использования"? Лично мне определенно понравился бы полный текстовый поиск и лучший браузер использования, и AJAX мог бы с этим справиться.

Хорошо, что хорошая идея о JavaDoc заключается в том, что она противоположна устаревшей - она ​​произвольно расширяема. Почему бы вам не пойти дальше и написать doclet, который создает нужный вам документ API?

Почему никто еще не сделал этого до сих пор (что, по-видимому, так и есть), кто-то догадывается - может быть, никто больше не будет так сильно об этом, как вы.

Ответ 8

Там DocBook doclet. DocBook - это более богатый тип документа, чем (X) HTML, и лучше для описания технического контента. Из источника DocBook вы можете создавать всевозможные различные форматы вывода.

Ответ 9

Мне лично хотелось бы получить более читаемую стандартную "документацию комментариев", чем HTML (и, следовательно, Tag-wieldy) JavaDoc.

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

С текущим JavaDoc я полагаю, что многие люди используют комментарии JavaDoc, но на самом деле не документируют, насколько могли. Я уверен, что каждый посетил API-интерфейс JavaDoc, который был не документирован или едва документирован, и, тем не менее, он сложнее использовать, чем должно быть.

Это не помогло преобразование кода (например, в Eclipse или, возможно, при фиксации источника), которые полностью уничтожают любую читаемую структуру, которую вы могли бы добавить в комментарий JavaDoc (например, список элементов) в один большой блок текста, если вы буквально не используете два возврата каретки там, где вы хотите их использовать).

Ответ 10

Кто-нибудь знает, если есть какие-то планы по развитию Джавадока, каким-то образом стандартизированным образом?

Соответствующий JSR (JSR 260), который указывает улучшения Javadoc, был отклонен из JDK 7 (на данный момент). Обзор планируемого (от этого сайта):

Обновите Javadoc, чтобы предоставить более богатый набор тегов, чтобы обеспечить более структурированное представление документации Javadoc. Этот JSR охватывает: категоризацию методов и полей, семантический индекс классов и пакетов, различие статических, factory, устаревшие методы от обычных методов, различие аксессуаров свойств, объединение и разделение информации на представления, внедрение примеров и общее использование - случаев и т.д.

Общий прогноз для JDK 7 довольно мрачный.

Ответ 11

JavaDoc сам по себе чрезвычайно гибкий, потому что вы можете заменить стандартный doclet специальным doclet, чтобы обеспечить что-то, что соответствует вашим конкретным проектам.

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

С этим мы смогли предоставить интерактивный пользовательский интерфейс с использованием одностраничного приложения (похожего на настольный инструмент), но все из браузера - без какого-либо кода или инфраструктуры на стороне сервера. Средство просмотра включало стандартные функции, такие как поиск, древовидная навигация и т.д.

Здесь ссылка на примерную точку входа в довольно обширную документацию: Пример просмотра JavaDoc

Здесь также изображение:

Ответ 12

Интеллектуальный считыватель javadoc:

Во многих случаях мне приходится сталкиваться с проблемой просмотра JavaDoc. Я искал что-то подобное, как вариант поиска документа Adnroid. Наконец-то я получу что-то подобное. Если вы используете firefox, то решение находится здесь.

• Установите плагин GreaseMonkey, его собственную веб-страницу настройки, как мы видим. (Нам нужно настроить любую страницу java doc, чтобы мы могли искать по имени класса)  https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

• Для работы greasemonkey нам нужен пользователь script для настройки. Это можно загрузить greasemonkey автоматически. Установите usercript из рамки поиска JavaDoc или инкрементный поиск по JavaDoc.

Это отлично работает для меня.