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

Question

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

В Интернете есть некоторые ресурсы, предлагающие повторное оформление Javadoc. Но поведение по умолчанию представляет собой продукт и должно быть столь же привлекательным.

Еще одна проблема заключается в том, что юзабилити Javadoc несовместимы с другими подобными ресурсами.

Особенно сложные проекты трудно перемещаться с помощью быстрого поиска Firefox.

Практический вопрос:
Есть ли какие-либо автономные (настольные) приложения, которые способны просматривать существующие Javadoc в более удобный способ, чем браузер будет?
Я думаю о чем-то вроде браузера документации Mono.

Теоретический вопрос:
Кто-нибудь знает, если есть какие-то планы развиваться Javadoc, в как-то стандартизированным способом?
EDIT:A useful link to Sun' wiki on this topic.

Answer 1

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

Answer 2

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

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

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

Answer 3

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

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

Answer 4

Возможно, вам понадобится фраза, которая менее агрессивно и властно. Большинство людей не заботятся о том, как выглядит технический ресурс, и «Это недостаточно для Web 2.0!» звучит как неистовый рыночный подход.

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

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

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

Answer 5

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

Для поиска: Используйте Javadoc Search Frame, это делает использование Javadoc всех видов намного проще. Он доступен как Userscript for Firefox и как Google Chrome Extension.

Answer 6

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

Answer 7

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

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

Таким образом, определенно по-прежнему продолжается работа там, даже если несколько поздно. Однако, на мой взгляд, одним из самых больших недостатков Javadoc является его очень тесная связь с HTML. Многие классы имеют Javadoc, который включает в себя литерал HTML и полагается на результат, являющийся HTML. К сожалению, но это не изменится в любое время, я думаю. Тем не менее, это означает, что разработчики могут включать в себя все, что захочет, в HTML, что также может быть недействительным, неверно сформированным и т. Д. Таким образом, адаптация вывода из инструмента javadoc является лишь частью этого, t и не может измениться и, таким образом, остается.

Что касается просмотра документации, я также нашел документацию HTML немного громоздкой. Обычно я использую представление Javadoc в Eclipse. У этого есть также недостатки (медленные, и вы не можете действительно искать), но для большинства вещей это Good Enough ™.

Answer 8

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

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

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

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

Answer 9

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

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

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

Общий прогноз по JDK 7: pretty grim.

Answer 10

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

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

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

Answer 11

Умный seachable зритель Javadoc:

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

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

2. Для Greasemonkey работать, нам нужно некоторое пользовательский скрипт для настройки. Это можно загрузить greasemonkey автоматически. Установите учетную запись с JavaDoc search frame или JavaDoc incremental search.

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

Answer 12

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

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

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

Вот ссылка на точку входа образца в довольно обширной документации: JavaDoc viewer sample

Вот изображение также: