JDK8：获取javadoc的JDK7外观 [英] JDK8: Getting back the JDK7 look for javadoc
问题描述
与JDK7相比，我发现在JDK8 javadoc中难以阅读新的外观。
这是一个并排的例子。
JDK7：
JDK8：
JDK8占用了相当多的空间。它现在使用之前使用Arial的DejaVu字体。可能有充分的理由。 Dunno。
我最大的问题是在参数和投掷部分中，参数与其描述之间不再有任何视觉差异。它们都是单声道间隔字体。我认为用单声道间隔字体书写描述性文字只是丑陋。单调间隔字体用于标识符，源代码列表等的名称。 （随意不同意）。
我是否可以在使用JDK8 javadoc工具时恢复JDK7样式？
我希望得到像这样的东西javadoc -stylesheet jdk7.css 其中 jdk7.css 是JDK8中包含的内容。此外，如果我决定自己定制css（不是我的东西，但可能没有其他解决方案），我不愿意在我们企业的每个构建服务器上确保新样式表的可用性。也许有一个Maven解决方案呢？
可能的解决方案？
有人建议（下面）使用
您可以使用javadoc命令行中的 stylesheetfile 属性，或命令行中的ant或maven
：
％javadoc -stylesheetfile< path> ...
在蚂蚁：
< javadoc
....
stylesheetfile =/ path / to / stylesheet.css
/> Maven中的
（参见 Maven的样式表配置页面了解更多详情）：
<报告> （或< 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> （或< / build>）
更新
Stephen Colebourne有一篇关于Java 8中对Javadoc的其他重大更改的文章这里。显然，doclint现在强制执行HTML 4 合规性，如果链接断开或100％正确HTML 4，则不会链接。您可以使用 -Xdoclint：none <关闭它/ code>作为附加参数。
< plugins>
< plugin>
< groupId> org.apache.maven.plugins< / groupId>
< artifactId> maven-javadoc-plugin< / artifactId>
< configuration>
< additionalparam> -Xdoclint：none< / additionalparam>
< / configuration>
< / plugin>
< / plugins>
关于< code> 标签参数说明，我也看到了。看起来javadoc中的参数描述现在总是等宽的，所以你不再需要代码标签了吗？
I find it difficult to read the new look-and-feel in JDK8 javadoc compared to JDK7. Here's a side-by-side example.
JDK7:
JDK8:
JDK8 takes up considerable more space. It now uses the DejaVu font where Arial was previously used. There may be good reasons for that. Dunno.
My biggest problem is in the "Parameters" and "Throws" sections where there's no longer any visual difference between the argument and its description. They are both in a mono spaced font. Writing descriptive text in mono spaced font is just ugly, I think. Mono spaced font is for names of identifiers, source code listings and the like. (feel free to disagree).
Can I get the JDK7 style back while still using the JDK8 javadoc tool?
I was hoping for something like javadoc -stylesheet jdk7.css where jdk7.css was something included with the JDK8. Also if I decide to customize the css on my own (not my thing, but there may be no other solution) I would hate to have to ensure availability of the new stylesheet on every build server in our enterprise. Perhaps there's a Maven solution for that ?
POSSIBLE SOLUTION ?
It has been suggested (below) to use the JDK7 javadoc css with the JDK8 javadoc tool to see if that would bring back some eligible Javadoc.
I've done my test by checking out the source code from the Apache Commons Lang project. I use only the source code, not their POM. This is to ensure that I know I'm working off the right base.
Okay, first - for reference - here's the Javadoc which has been produced by an all JDK7 toolchain (JDK7 javadoc tool, JDK7 css). Here's the POM snippet:
<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>
and the resulting Javadoc:
Next, the attempt to use the JDK7 css with the JDK8 javadoc tool. Here's the POM snippet:
<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>
and the resulting Javadoc:
So, as you can see, this strategy did not work out for me.
UPDATE
I've just realized that a consequence of this change is that it has become pointless to use {@code } (or <code>) markup on parameter descriptions. It doesn't show anyway. In other words if you liked to do like this in past:
/**
* ...
* @param eName the name for the entity or <code>null</code> to use the default
* ...
*/
there's simply no point to that anymore. Your null text will not stand out anyway.
The css used in Java 7's Javadoc can be found here:
http://docs.oracle.com/javase/7/docs/api/stylesheet.css
You can then use the stylesheetfile attribute from the javadoc commandline, or ant or maven
from commandline:
%javadoc -stylesheetfile <path> ...
in ant:
<javadoc
....
stylesheetfile="/path/to/stylesheet.css"
/>
in Maven (see Maven's stylesheet configuration page for more details ):
<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>)
UPDATE
Stephen Colebourne has an article about other breaking changes to Javadoc in Java 8 here . Apparently, the doclint now enforces HTML 4 compliance and will not link if the link is broken or not 100% correct HTML 4. You can turn it off with -Xdoclint:none as an additional parameter.
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<additionalparam>-Xdoclint:none</additionalparam>
</configuration>
</plugin>
</plugins>
Regarding the <code> tags in parameter descriptions, I did see that too. It looks like the parameter descriptions in javadoc are now always monospace so you don't need code tags anymore?
这篇关于JDK8：获取javadoc的JDK7外观的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
