Вопрос или проблема
Я хотел бы иметь возможность программно преобразовывать Javadoc комментарии (такие как в сгенерированном коде LWJGL) в другие форматы (например, Markdown). Это позволило бы мне делать такие вещи, как автоматическая генерация идиоматического Clojure обертки для LWJGL с человекочитаемыми документационными строками.
Я могу извлечь Javadoc комментарии из исходного файла с помощью JavaParser, но здесь я застреваю. Ответы на эти два вопроса на Stack Overflow 2011 и 2013 годов рекомендуют использовать Doclet API, но согласно ответу на этот вопрос 2015 года:
Классы в пакетах
com.sun.tools.*должны рассматриваться как внутренние API. В документации по Java есть четкие предупреждения о том, что вы не должны писать код, который зависит от этих API.Например:
В Java 8 заголовок класса, который ваш код пытается использовать, говорит:
Это НЕ часть какого-либо поддерживаемого API. Если вы пишете код, который зависит от этого, вы делаете это на свой страх и риск. Этот код и его внутренние интерфейсы могут быть изменены или удалены без предупреждения.
(Жирный текст в оригинале!)
В Java 7 этого не было (больно!). Действительно, есть версии часто задаваемых вопросов по Javadoc, которые, похоже, поощряют людей повторно использовать стандартные классы doclet. К сожалению, Oracle решили закрыть эти классы и также внесли некоторые нарушающие изменения в API, что это подтверждает, хотели они этого или нет.
Поиск в Google по запросу “Javadoc parser” не дал ничего, кроме самого Doclet. Поскольку Doclet не поддерживается, мне кажется, что лучшее решение моей проблемы — написать библиотеку для парсинга Javadoc самостоятельно. Однако мне кажется маловероятным, что такого рода библиотека еще не существует. Я не являюсь экспертом по Javadoc; возможно, нет стандартного “формата Javadoc”, и вопрос “как я могу разобрать Javadoc” неверный.
Мне нужна библиотека на Java, которая
- принимает строку комментария Javadoc (например,
"/** foo */") и возвращает некий парсинговый деревo - не зависит от каких-либо внутренних частей JDK (таких как
tools.jar) - доступна через какой-либо публичный репозиторий Maven (например, Central или Clojars)
- не говорит “не используйте это” в своей документации
Существует ли поддерживаемая библиотека для парсинга Javadoc, или мне следует написать одну самостоятельно?
Существует проект doc2java, который поддерживает это:
Существует также поисковая система, которая может размещать JavaDocs и делать их доступными для поиска.
Ссылки
Ответ или решение
Библиотека Java для парсинга комментариев Javadoc
Вопрос о программном преобразовании комментариев Javadoc в другие форматы, такие как Markdown, становится особенно актуальным для разработчиков, работающих с API, такими как LWJGL. Постоянно меняющийся ландшафт API и закрытые библиотеки, включая внутренние пакеты JDK, подчеркивают важность поиска надежного решения. Давайте обсудим, какие существуют библиотеки для парсинга Javadoc и что может быть сделано.
Актуальные проблемы
-
Зависимость от внутренних API JDK: Многие рекомендации по использованию API, таких как Doclet, устарели. Oracle предостерегает разработчиков от использования пакетов
com.sun.tools.*, которые могут подвергаться изменениям без уведомлений. -
Отсутствие поддерживаемых библиотек: Попытки найти готовую библиотеку, которая удовлетворяет критериям, таким как отсутствие зависимостей от внутренних JDK и доступность в публичных Maven-репозиториях, часто оказываются неудачными.
Возможные решения
На основании изложенных требований рассмотрим несколько библиотек и проектов, которые могут помочь в парсинге комментариев Javadoc:
-
doc2java:
- Этот проект представляет собой средство для обработки комментариев Javadoc и может создавать структуры данных на основе вводимых комментариев. Он поддерживает преобразование Javadoc в различные форматы, включая Markdown.
- Вы можете ознакомиться с кодом и документацией на GitHub-репозитории doc2java.
-
JavaParser:
- Поскольку вы уже упомянули о JavaParser, следует отметить, что эта библиотека в первую очередь предназначена для парсинга исходного кода Java. Однако, извлечение комментариев Javadoc из туториалов может быть лишь частью задачи. Для полной реализации вам, вероятно, потребуется дополнительно реализовать парсер для самой разметки Javadoc.
-
Javadoc.IO:
- Этот сервис не предоставляет парсинг как таковой, но может использоваться для хостинга и поиска Javadoc. Его функциональность может быть интересной для дополнительной информации о проекте или его документации. Вы можете ознакомиться с Javadoc.IO.
Написание собственного парсера
Если готовые решения не удовлетворяют ваши потребности, возможно, имеет смысл разработать собственный парсер. Вот шаги, которые можно предпринять:
- Исследование формата Javadoc: Понимание разметки Javadoc и правил синтаксиса является ключевым шагом для создания парсера.
- Выбор подходящей реализации: Вы можете использовать библиотеки для работы с текстами, такие как ANTLR, для определения грамматики и создания парсера.
- Создание AST: Разработка абстрактного синтаксического дерева (AST), на основе которого можно будет производить преобразования в другие форматы, такие как Markdown.
Заключение
На настоящий момент отсутствуют широко распространенные и поддерживаемые библиотеки для парсинга Javadoc, которые соответствуют всем изложенным критериям. Но существуют проекты, такие как doc2java, которые могут помочь с вашей задачей. В случае, если вам необходим более специфичный функционал, следует рассмотреть написание собственного парсера для ваших нужд.
Надеюсь, данная информация окажется полезной для вас.