plugin - generate javadoc eclipse maven

JDK8: Recuperar el aspecto JDK7 para javadoc

Question

Me resulta difícil leer el nuevo look-and-feel en JDK8 javadoc en comparación con JDK7. Aquí hay un ejemplo de lado a lado.

JDK7:

JDK8:

JDK8 ocupa mucho más espacio. Ahora usa la fuente DejaVu donde se usó Arial anteriormente. Puede haber buenas razones para eso. No sé.

Mi mayor problema se encuentra en las secciones "Parámetros" y "Tiros", donde ya no hay ninguna diferencia visual entre el argumento y su descripción. Ambos están en una fuente mono espaciada. Escribir texto descriptivo en una fuente mono espaciada es feo, creo. La fuente espaciada mono es para nombres de identificadores, listados de código fuente y similares. (siéntase libre de estar en desacuerdo).

¿Puedo recuperar el estilo JDK7 mientras sigo utilizando la herramienta javadoc JDK8?

Esperaba algo como javadoc -stylesheet jdk7.css donde jdk7.css era algo incluido con el JDK8. Además, si decido personalizar el css por mi cuenta (no es lo mío, pero puede que no haya otra solución), no me gustaría tener que asegurar la disponibilidad de la nueva hoja de estilo en cada servidor de compilación en nuestra empresa. Tal vez hay una solución de Maven para eso?

SOLUCIÓN POSIBLE ?

Se ha sugerido (a continuación) utilizar JDK7 javadoc css con la herramienta JDK8 javadoc para ver si eso devolvería algún Javadoc elegible.

He realizado mi prueba comprobando el código fuente del proyecto Apache Commons Lang. Uso solo el código fuente, no su POM. Esto es para asegurar que sé que estoy trabajando con la base correcta.

Bueno, primero, para referencia, aquí está el Javadoc que ha sido producido por una cadena de herramientas JDK7 (JDK7 javadoc, JDK7 css). Aquí está el fragmento de POM:

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<configuration>
<stylesheetfile>${basedir}/src/main/css/jdk7javadoc.css</stylesheetfile>
<javadocExecutable>C:/Program Files/Java/jdk1.7.0_55/bin</javadocExecutable>
</configuration>
</plugin>
</plugins>
</build> 

y el Javadoc resultante:

A continuación, el intento de usar el css de JDK7 con la herramienta javadoc de JDK8. Aquí está el fragmento de POM:

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<configuration>
<stylesheetfile>${basedir}/src/main/css/jdk7javadoc.css</stylesheetfile>
<javadocExecutable>C:/Program Files/Java/jdk1.8.0_05/bin</javadocExecutable>
</configuration>
</plugin>
</plugins>
</build> 

y el Javadoc resultante:

Entonces, como puedes ver, esta estrategia no funcionó para mí.

ACTUALIZAR

Acabo de darme cuenta de que una consecuencia de este cambio es que no tiene sentido usar el marcado {@code } (o <code> ) en las descripciones de los parámetros. No se muestra de todos modos. En otras palabras, si te gustó hacer esto en el pasado:

/**
* ...
* @param eName the name for the entity or <code>null</code> to use the default
* ...
*/

Simplemente no hay ningún punto para eso más. Su texto null no se destacará de todos modos.

Answer 1

El css utilizado en Java 7''s Javadoc se puede encontrar aquí:

http://docs.oracle.com/javase/7/docs/api/stylesheet.css

Luego puede usar el atributo stylesheetfile desde la línea de comandos de javadoc, o ant o maven

desde la línea de comandos:

%javadoc -stylesheetfile <path> ...

en hormiga

<javadoc
....
stylesheetfile="/path/to/stylesheet.css"
/> 

en Maven (vea la página de configuración de la hoja de estilo de Maven para más detalles ):

<reporting> (or <build>)
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
...
<configuration>
<stylesheetfile>${basedir}/path/to/your/stylesheetfile.css</stylesheetfile>
...
</configuration>
</plugin>
</plugins>
...
</reporting> (or </build>) 

ACTUALIZAR

Stephen Colebourne tiene un artículo sobre otros cambios de última hora en Javadoc en Java 8 here . Aparentemente, doclint ahora impone el cumplimiento de HTML 4 y no se vinculará si el enlace está roto o no es 100% correcto HTML 4. Puede desactivarlo con -Xdoclint:none como un parámetro adicional.

<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<additionalparam>-Xdoclint:none</additionalparam>
</configuration>
</plugin>
</plugins>

Con respecto a las etiquetas <code> en las descripciones de los parámetros, también vi eso. Parece que las descripciones de los parámetros en javadoc ahora son siempre monoespaciales, ¿así que ya no necesitas las etiquetas de código?

Answer 2

Puede obtener el JDK 8 stylesheet.css estándar y repararlo muy rápidamente, y luego puede colocarlo en alguna carpeta de origen y decirle a javadoc que lo use con su opción de archivo de stylesheetfile . El problema con eso es que no hay garantía de compatibilidad con versiones anteriores, el HTML generado cambia bastante a veces. Eso sucedió con JDK 7, y ahora con JDK 8. Y, a menudo, también hay que tener en cuenta que solo porque JDk 8 está fuera, algunos pueden construir su proyecto con JDK 7 ...

De todos modos, lo que hice fue detectar si estamos construyendo bajo JDK 8 o posterior, y en ese caso he aplicado reemplazos de expresiones regulares en stylesheet.css , en tiempo de compilación. Eso fue fácil para mí, ya que este viejo proyecto usa Ant, no Maven. Solo para ver cuáles son los cambios, la parte relevante es:

<target name="_fixJDK8JavadocCSS" depends="_rawJavadoc" if="atLeastJDK8">
<property name="file" value="build/api/stylesheet.css" />
<echo>Fixing JDK 8 CSS in ${file}</echo>
<!-- Tell that it''s modified: -->
<replaceregexp
file="${file}" flags="gs" encoding="utf-8"
match="//* (Javadoc style sheet) /*/" replace="//* /1 - JDK 8 usability fix regexp substitutions applied /*/"
/>
<!-- Remove broken link: -->
<replaceregexp
file="${file}" flags="gs" encoding="utf-8"
match="@import url/(''resources/fonts/dejavu.css''/);/s*" replace=""
/>
<!-- Font family fixes: -->
<replaceregexp
file="${file}" flags="gsi" encoding="utf-8"
match="[''&quot;]DejaVu Sans[''&quot;]" replace="Arial"
/>
<replaceregexp
file="${file}" flags="gsi" encoding="utf-8"
match="[''&quot;]DejaVu Sans Mono[''&quot;]" replace="''Courier New''"
/>
<replaceregexp
file="${file}" flags="gsi" encoding="utf-8"
match="[''&quot;]DejaVu Serif[''&quot;]" replace="Arial"
/>
<replaceregexp
file="${file}" flags="gsi" encoding="utf-8"
match="(?&lt;=[/s,:])serif/b" replace="sans-serif"
/>
<replaceregexp
file="${file}" flags="gsi" encoding="utf-8"
match="(?&lt;=[/s,:])Georgia,/s*" replace=""
/>
<replaceregexp
file="${file}" flags="gsi" encoding="utf-8"
match="[''&quot;]Times New Roman[''&quot;],/s*" replace=""
/>
<replaceregexp
file="${file}" flags="gsi" encoding="utf-8"
match="(?&lt;=[/s,:])Times,/s*" replace=""
/>
<replaceregexp
file="${file}" flags="gsi" encoding="utf-8"
match="(?&lt;=[/s,:])Arial/s*,/s*Arial/b" replace="Arial"
/>
<!-- "Parameters:", "Returns:", "Throws:", "Since:", "See also:" etc. fixes: -->
<property name="ddSelectorStart" value="(?:/.contentContainer/s+/.(?:details|description)|/.serializedFormContainer)/s+dl/s+dd/b.*?/{[^/}]*/b" />
<property name="ddPropertyEnd" value="/b.+?;" />
<!-- - Put back description (dd) indentation: -->
<replaceregexp
file="${file}" flags="gs" encoding="utf-8"
match="(${ddSelectorStart})margin${ddPropertyEnd}" replace="/1margin: 5px 0 10px 20px;"
/>
<!-- - No monospace font for the description (dd) part: -->
<replaceregexp
file="${file}" flags="gs" encoding="utf-8"
match="(${ddSelectorStart})font-family${ddPropertyEnd}" replace="/1"
/>
</target>

Entonces, el punto es la expresión regular anterior, que cualquiera puede aplicar con ant , sed , Notepad ++, etc. (para no Ant, no olvide resolver las partes &...; y ${...} ).

La razón por la que he usado regexp es que espero que pueda sobrevivir a algunos cambios en el HTML y, por lo tanto, en el CSS estándar ... pero tal vez debería usar el CSS resultante, no lo sé. O debería optar por usar algún doclet de terceros, donde así puedo controlar la versión usada.

Answer 3

Utilizo una hoja de estilo para anular algunas de las definiciones de CSS de JDK8, para que se vea más como JDK7 Javadoc.

@import "stylesheetOrig.css";
body {
font-family: Arial, Helvetica, sans-serif;
font-size: 12px; }
pre {
font-family: monospace;
font-size: 12px; }
code, tt, dt code, table tr td dt code {
font-family: monospace;
font-size: 12px; }
.contentContainer .description dl dt, .contentContainer .details dl dt, .serializedFormContainer dl dt {
font-size: 13px; }
.contentContainer .description dl dd, .contentContainer .details dl dd, .serializedFormContainer dl dd {
margin-left: 20px;
font-size: 12px;
font-family: inherit; }
div.block {
font-size: 12px;
font-family: inherit; }
h4 {
font-size: 15px; }
.memberSummary caption {
padding-top: 0; }
div.summary th {
border: 1px solid #9eadc0; }
div.summary td {
border-left: 1px solid #9eadc0;
border-right: 1px solid #9eadc0; }
div.summary th.colFirst,
div.summary td.colFirst {
border-right: none; }
div.summary th.colLast,
div.summary td.colLast {
border-left: none; }
div.summary table {
border-bottom: 1px solid #9eadc0;
margin-bottom: 15px; }
div.summary ul.blockList ul.blockList ul.blockList {
margin-top: 20px; }
ul.blockList ul.blockList li.blockList,
ul.blockList ul.blockList ul.blockList li.blockList,
ul.blockList ul.blockList ul.blockListLast li.blockList {
border: 1px solid #9eadc0; }
div.summary ul.blockList ul.blockList ul.blockList li.blockList h3,
div.details ul.blockList ul.blockList ul.blockList li.blockList h4,
div.details ul.blockList ul.blockList ul.blockListLast li.blockList h4 {
border-bottom: 1px solid #9eadc0; }

My Ant script cambia el nombre del archivo stylesheet.css original a stylesheetOrig.css y lo reemplaza por la nueva versión (que importa la versión original):

<condition property="isJava8">
<equals arg1="${ant.java.version}" arg2="1.8"/>
</condition>
<target name="-fixupJava8Javadoc" if="isJava8">
<move file="target/apidocs/stylesheet.css" tofile="target/apidocs/stylesheetOrig.css"/>
<copy file="src/doc/javadoc8OverrideStylesheet.css" tofile="target/apidocs/stylesheet.css"/>
</target>