Библиотека Java для разбора комментариев Javadoc

Я хотел бы иметь возможность программно преобразовывать комментарии 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, которая

  1. принимает строку комментария Javadoc (например, "/** foo */") и возвращает своего рода дерево синтаксического анализа
  2. не зависит ни от каких внутренних частей JDK (таких как tools.jar)
  3. доступен через общедоступный репозиторий Maven (например, Central или Clojars )
  4. не говорит «не используйте это» в своей документации

Существует ли поддерживаемая библиотека синтаксического анализа Javadoc или мне следует написать ее самостоятельно?

Приведенный вами ответ неверен. Он путает sun.*пакеты, о которых есть известное предупреждение, с com.sun.*пакетами, о которых его нет. com.sun.*Например, было бы невозможно написать программу JNDI без использования .
Согласно этому ответу , tools.jarкоторый включает в себя com.sun.javadoc.*, «не может быть распространен». Итак, как я могу распространять приложение, которое зависит от com.sun.javadoc.*? Или это не тот пакет, который мне понадобится для программного анализа комментариев Javadoc?
Вы не можете. Вы должны полагаться на JDK, установленный на цели. Но это другой вопрос. И зачем приложению без JDK обрабатывать исходный код Java?
Очевидно, участники JavaParser считают, что обработка исходного кода Java без использования JDK — вполне разумная вещь. Кроме того, Clojure не требует JDK , поэтому вариант использования, который я привел в самом начале моего вопроса, является еще одним примером.
Это совсем не одно и то же. Они не зависят от JDK, потому что вам не нужен JDK для написания синтаксического анализатора. У вас есть зависимость от JDK, нет двух способов. Но опять же, это новый вопрос и ничего общего с этим ответом.
Это имеет отношение к этому ответу. API Doclet, помимо того, что он «НЕ является частью какого-либо поддерживаемого API» (или, возможно, из-за этого), также обычно недоступен программно во время выполнения, поскольку для него требуется JDK. Это не решение проблемы, которую я описал в своем вопросе.
Вы могли бы написать это сами с кучей усилий. Почему бы вам просто не использовать Doclet? а) Это работает .. сейчас . б) если API, которые вы хотите от Doclet, когда-либо исчезнут, вы можете взять старый исходный код Doclet и обращаться с ним как с вашим, как если бы вы его написали.
@IraBaxter Не могли бы вы опубликовать ссылку на часть исходной лицензии Doclet, в которой говорится, что мне разрешено рассматривать ее как свою?
Хорошо, справедливое замечание. Я хочу сказать, что вы можете сделать кучу работы сейчас или просто отложить эту работу. Худшее, что может случиться, это то, что вам придется писать такой инструмент, когда Doclet исчезнет; это не может быть хуже, чем написать этот инструмент сейчас, и выигрыш в том, что вам, возможно, никогда не придется. API существуют намного дольше, чем кто-либо может признать.
@IraBaxter Это определенно имеет смысл, но для этого мне потребуется изучить API Doclet, чего мне не нужно делать, если я просто напишу библиотеку сейчас. Кроме того, это не решает того факта, что все, что я пишу с использованием API Doclet, становится труднее распространять.

Ответы (1)

Существует проект doc2java, который поддерживает это:

проект doc2java

Существует также поисковая система, которая может размещать JavaDocs и делать их доступными для поиска.

использованная литература

Разве это не наоборот? Похоже, у OP есть код Java, и он хочет, чтобы из него были только комментарии «javadoc»? Я думаю, что лучшим инструментом может быть, например, doxygen и вывод XML для дальнейшей обработки.
@albert Я только что попал сюда из поисковой системы и, судя по заголовку, ответил на вопрос
Я думаю, что более подходящие ответы с помощью Google можно получить, например: docs.oracle.com/javase/6/docs/technotes/guides/javadoc/doclet/… или tomassetti.me/… или stackoverflow.com/questions/24727110/ …
@Альберт Спасибо. Надеюсь, ОП ответит.
Да, как сказал @albert, это не отвечает на вопрос.
@SamEstep Вы ознакомились с моими предложениями (я не углублялся в них, поэтому не уверен, чего они стоят в отношении вопроса) или вы нашли другое решение (если да, пожалуйста, добавьте в свой вопрос или сообщение в качестве ответа, в зависимости от того, является ли это обходным путем или хорошим решением)
@albert Я сделал; Doclet не будет работать по причинам, которые я упомянул в исходном вопросе, и, как говорится в этой статье, хотя JavaParser может извлекать комментарии JavaDoc самостоятельно, он не может их анализировать (и соответствующая проблема, указанная в конце статьи, была закрыта). Я еще не нашел хорошего решения.
@SamEstep Просто попробуйте doxygen с выводом xml (просто установите EXTRACT_ALL в YES и GENERATE_XML в YES) и посмотрите, что вы получите в каталоге xml, возможно, вы сможете проанализировать это дальше.
@albert Это хорошая идея, спасибо; У меня давно не было времени поработать над этим проектом, но если я вернусь к нему, я обязательно попробую.
Библиотека Java для разбора комментариев Javadoc
СпросиСетьПолитика конфиденциальности1y, 0v