Как сделать встроенные теги (которые требуют com.sun) более кроссплатформенными? Есть ли не Oracle/ более кросс-платформенный анализатор javadoc?

Question

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

{@.codelet.and.out my.package.AGreatExample}
{@.codelet my.package.AGreatExample}
{@.file.textlet examples\doc-files\an_input_file.txt}
{@.codelet.and.out my.package.AGreatExample%eliminateCommentBlocksAndPackageDecl()}

Так как пользовательские теги (и даже доклеты) требуют com.sun это означает, что они не так кроссплатформенны, как сама Java. (Не уверен, что это уместно, но слово "javadoc"- и даже подстрока "doc"- отсутствует в Спецификациях языка Java 8.)

Мне не нравится идея написания такой ограниченной библиотеки. Так что мне делать? Мои мысли пока что

• Чтобы использовать преимущества существующего синтаксического анализатора Javadoc, я придерживаюсь com.sun taglets. Тем не менее, я делаю эту опору на com.sun настолько "тонкий", насколько это возможно. То есть я поместил как можно меньше кода в класс taglet, оставив большую часть кода в другом месте, где нет никакой зависимости от com.sun,
• Я работаю над созданием собственного парсера, который ищет только мои конкретные теги. Это боль, но не слишком ужасная. Вы перебираете строки каждого исходного файла Java, ища \{@\.myTagletName (.*?)\}, Как только вы захватите этот текст, он будет примерно таким же, как и код внутри com.sun taglet.
• Этот синтаксический анализатор должен быть запущен перед выполнением Javadoc, и, следовательно, потребуется дублированная структура каталогов. (1) ваш исходный код с непарсированными пользовательскими тегами, (2) дубликат этого кода с анализом-выводом. Я скопировал бы весь код в дубликат каталога, а затем проанализировал только те Java-файлы, которые, как известно, имеют эти теги (классы, которые каким-то образом "зарегистрированы" с помощью синтаксического анализатора).

Это разумный подход? Есть ли уже более кроссплатформенный парсер javadoc / taglet, так что мне не нужно накатывать свой собственный? Есть ли что-нибудь кроссплатформенное, похожее на taglet, уже там? Является ли сам JavaDoc кроссплатформенным или просто пользовательскими теглетами и доклетами?

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

(Несмотря на мою ссылку на Java 8 выше, я использую Java 7.)

---

Благодарим @fge за предложение по тегу, которое более элегантно, чем моя оригинальная идея, и @Michael за зловещий, но полезный com.sun предупреждения.

Answer 1

Во-первых, обратите внимание, что есть разница между sun.* а также com.sun.* зависимостей. sun.* Пространство имен содержит классы, которые реализуют виртуальную машину Java Oracle. Вы не должны использовать такие зависимости, потому что внутренний API Oracle JVM может измениться в будущих выпусках и потому что это пространство имен может не предоставляться другими реализациями JVM, отличными от Oracle. (На практике даже Android JVM поставляется с одним из наиболее широко используемых sun.* классы.)

Тогда есть com.sun.* пространство имен, которое использовалось Sun Microsystems для реализации своих Java-приложений. Пример легального использования com.sun.* зависимости является основой Джерси Sun, который был первоначально развернут в com.sun.jersey.* Пространство имен. (Ради полноты, обратите внимание, что последние версии Джерси развернуты в org.glassfish.jersey.* пространство имен, начиная с версии 2.0, которая несовместима с API Джерси 1.) Для дальнейшего ознакомления обратите внимание, что Oracle даже не упоминает com.sun.* пространство имен при обсуждении проблем, которые налагаются с помощью sun.* Пространство имен. Также см. Этот связанный вопрос о переполнении стека.

Поэтому, используя com.sun.* зависимости это другая сделка по сравнению с sun.* зависимостей. Используя com.sun.* классы, вы скорее привязываетесь к API конкретной библиотеки, а не к конкретной JVM. Например, вы можете избежать прямого использования com.sun.jersey.* пространство имен с использованием стандартизированного JAX-RS javax.ws.rs.* Пространство имен. В этом смысле, com.sun.* зависимости являются специфичными для продукта и проприетарными, и их не следует путать со стандартными API-интерфейсами Java, которые обычно находятся в javax.* Пространство имен.

Если бы я был тобой, я бы придерживался taglets, который является зрелой и признанной реализацией. Oracle довольно решительно настроен не нарушать API (в противном случае они, вероятно, также переместят теглеты в com.oracle.*) и я не вижу причин, по которым они внезапно изменили бы структуру пакета taglet. И если они это сделают, вам просто нужно обновить свои технологии. Если ваше приложение перестает работать на новый выпуск Java, ваши пользователи будут искать обновление вашего программного обеспечения. Поскольку вы не запускаете проект taglet, я согласен с вами в том, что отсоединение вашей логики от стороннего API в целом является хорошей идеей, как и для любой зависимости. Кроме того, использование тэглетов для вашего случая использования в значительной степени признает принципы KISS и DRY.