Biblioteca de Java para analizar los comentarios de Javadoc

Me gustaría poder convertir mediante programación los comentarios de Javadoc (como los del código generado de LWJGL ) a otros formatos (como Markdown ). Esto me permitiría hacer cosas como generar automáticamente un envoltorio Clojure idiomático para LWJGL con cadenas de documentos legibles por humanos.

Puedo seleccionar los comentarios de Javadoc de un archivo fuente usando JavaParser , pero ahí es donde me quedo atascado. Las respuestas a estas dos preguntas de Stack Overflow de 2011 y 2013 recomiendan usar la API de Doclet , pero de acuerdo con la respuesta a esta pregunta de 2015:

Las clases en los com.sun.tools.*paquetes deben tratarse como API internas. Hay advertencias claras en la documentación de Java que dicen que no debe escribir código contra estas API.

Por ejemplo:

En Java 8, el encabezado de la clase que su código intenta usar dice:

Esto NO es parte de ninguna API compatible. Si escribe código que depende de esto, lo hace bajo su propio riesgo. Este código y sus interfaces internas están sujetos a cambios o eliminación sin previo aviso.

(¡La negrita está en el original!)

No dijo eso en Java 7 (¡ay!) De hecho, hay versiones de las preguntas frecuentes de Javadoc que parecen alentar a las personas a reutilizar las clases de doclet estándar. Desafortunadamente, Oracle decidió cerrar estas clases y también realizó algunos cambios importantes en la API que refuerzan esto, ya sea que esa sea la intención de los cambios o no.

Una búsqueda en Google de "analizador Javadoc" no arrojó nada más que Doclet. Dado que Doclet no es compatible, me parece que la mejor manera de resolver mi problema sería escribir una biblioteca de análisis de Javadoc yo mismo. Sin embargo, me parece inverosímil que tal cosa no exista ya. No soy un experto en Javadoc; tal vez no haya un "formato Javadoc" estándar y la pregunta "¿cómo puedo analizar un Javadoc" es incorrecta ?

Me gustaría una biblioteca de Java que

  1. toma una cadena de comentarios de Javadoc (como "/** foo */") y devuelve algún tipo de árbol de análisis
  2. no depende de ninguna parte interna del JDK (como tools.jar)
  3. está disponible a través de algún repositorio público de Maven (como Central o Clojars )
  4. no dice "no use esto" en su documentación

¿Existe una biblioteca de análisis de Javadoc compatible o debo escribir una yo mismo?

La respuesta que citaste es incorrecta. Confunde los sun.*paquetes, sobre los que hay una conocida advertencia, con los com.sun.*paquetes, sobre los que no la hay. Sería imposible escribir un programa JNDI sin usar com.sun.*, por ejemplo.
De acuerdo con esta respuesta , tools.jarque incluye com.sun.javadoc.*, "no se puede distribuir". Entonces, ¿cómo puedo distribuir una aplicación que depende de com.sun.javadoc.*? ¿O no es ese el paquete que necesitaría para analizar los comentarios de Javadoc mediante programación?
no puedes Debe confiar en que se instale un JDK en el destino. Pero esta es una pregunta diferente. ¿Y por qué una aplicación sin un JDK necesitaría procesar el código fuente de Java?
Obviamente, los colaboradores de JavaParser creen que procesar el código fuente de Java sin usar el JDK es algo perfectamente razonable. Además, Clojure no requiere un JDK , por lo que el caso de uso que di al comienzo de mi pregunta es otro ejemplo.
No es lo mismo en absoluto. No dependen del JDK porque no necesita un JDK para escribir un analizador. Tiene una dependencia en el JDK, no hay dos formas de hacerlo. Pero nuevamente, esta es una pregunta nueva y no tiene nada que ver con esta respuesta.
Tiene todo que ver con esta respuesta. La API de Doclet, además de "NO ser parte de ninguna API admitida" (o quizás por eso), generalmente tampoco está disponible mediante programación en tiempo de ejecución porque requiere un JDK. No es una solución al problema que describí en mi pregunta.
Podrías escribir esto tú mismo con un montón de esfuerzo. ¿Por qué no usas Doclet? a) Funciona... ahora . b) si las API que desea de Doclet alguna vez desaparecen, puede tomar la fuente de Doclet más antigua y tratarla como si fuera suya, como si la hubiera escrito usted.
@IraBaxter ¿Podría publicar un enlace a la parte de la licencia de origen de Doclet que dice que puedo tratarlo como mío?
Bien, punto justo. Mi punto es que puedes elegir hacer un montón de trabajo ahora, o simplemente retrasar ese trabajo. Lo peor que sucede es que tiene que escribir una herramienta de este tipo cuando Doclet desaparece; eso no puede ser peor que escribir esa herramienta ahora, con la ventaja de que es posible que nunca tenga que hacerlo. Las API duran mucho más de lo que nadie admitirá.
@IraBaxter Eso definitivamente tiene sentido, pero eso requeriría que aprenda la API de Doclet, lo que no necesitaría hacer si solo escribo la biblioteca ahora. Además, no aborda el hecho de que todo lo que escribo que usa la API de Doclet se vuelve más difícil de distribuir.

Respuestas (1)

Hay un proyecto doc2java que admite esto:

proyecto doc2java

También hay un motor de búsqueda que puede albergar JavaDocs y hacer que se puedan buscar.

Referencias

¿No es esto al revés? ¿Parece que OP tiene el código Java y solo quiere sacar los comentarios 'javadoc'? Creo que una mejor herramienta podría ser, por ejemplo, doxygen y generar una salida XML para su posterior procesamiento.
@albert Acabo de llegar aquí desde un motor de búsqueda y siguiendo el título, respondí la pregunta
Creo que se pueden obtener respuestas más apropiadas con Google, tal vez algo como: docs.oracle.com/javase/6/docs/technotes/guides/javadoc/doclet/… o tomassetti.me/… o stackoverflow.com/questions/24727110/ …
@alberto Gracias. Esperemos que el OP responda.
Sí, como dijo @albert, esto no responde la pregunta.
@SamEstep ¿Echó un vistazo a las sugerencias que le di (no analicé profundamente, así que no estoy seguro de lo que valen con respecto a la pregunta) o encontró otra solución (si es así, agréguela a su pregunta o publicación como respuesta, dependiendo de si es una solución temporal o una buena solución)
@albert lo hice; Doclet no funcionaría por las razones que mencioné en la pregunta original, y como dice ese artículo, si bien JavaParser puede extraer los comentarios de JavaDoc, no puede analizarlos (y se cerró el problema relevante vinculado al final del artículo). Todavía no he encontrado una buena solución.
@SamEstep Solo pruebe doxygen con salida xml (solo configure EXTRACT_ALL en SÍ y GENERATE_XML en SÍ) y vea lo que obtiene en el directorio xml, tal vez pueda analizar esto más a fondo.
@albert Esa es una buena idea, gracias; No he tenido tiempo para trabajar en este proyecto por un tiempo, pero si vuelvo a él, me aseguraré de intentarlo.
Biblioteca de Java para analizar los comentarios de Javadoc
RespuestasAquíPolítica de privacidad1y, 2v