JDK8:找回 JDK7 寻找 javadoc [英] JDK8: Getting back the JDK7 look for javadoc

查看:51
本文介绍了JDK8:找回 JDK7 寻找 javadoc的处理方法,对大家解决问题具有一定的参考价值,需要的朋友们下面随着小编来一起学习吧!

问题描述

与 JDK7 相比,我发现很难阅读 JDK8 javadoc 中的新外观.这是一个并排示例.

JDK7:

JDK8:

JDK8 占用更多空间.它现在使用之前使用 Arial 的 DejaVu 字体.这可能有很好的理由.我不知道.

我最大的问题是参数"和投掷"参数与其描述之间不再有任何视觉差异的部分.它们都是单间距字体.我认为,用单行距字体编写描述性文本很难看.等距字体用于标识符名称、源代码列表等.(如有不同意见,请随意).

我可以在仍然使用 JDK8 javadoc 工具的同时恢复 JDK7 风格吗?

我希望有类似 javadoc -stylesheet jdk7.css 的东西,其中 jdk7.css 是包含在 JDK8 中的东西.此外,如果我决定自己定制 css(不是我的事,但可能没有其他解决方案),我将不愿意确保在我们企业中的每个构建服务器上都可以使用新样式表.也许有一个 Maven 解决方案?

可能的解决方案?

建议(下​​面)使用 .已在 Java 9 及更高版本中修复,未向后移植到 Java 8.

解决方案

Java 7 的 Javadoc 中使用的 css 可以在这里找到:

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

然后您可以使用 javadoc 命令行或 ant 或 maven 中的 stylesheetfile 属性

来自命令行:

%javadoc -stylesheetfile <路径>...

在蚂蚁中:

在 Maven 中(参见 Maven 的样式表配置页面了解更多信息详情):

(或<build>)<插件><插件><groupId>org.apache.maven.plugins</groupId><artifactId>maven-javadoc-plugin</artifactId>...<配置><stylesheetfile>${basedir}/path/to/your/stylesheetfile.css</stylesheetfile>...</配置></插件></插件>...</报告>(或</build>)

更新

Stephen Colebourne 发表了一篇关于 Java 8 中 Javadoc 其他重大更改的文章 这里 .显然,doclint 现在强制执行 HTML 4 合规性,如果链接损坏或不是 100% 正确的 HTML 4,则不会链接.您可以使用 -Xdoclint:none 关闭它作为附加参数.

<插件><groupId>org.apache.maven.plugins</groupId><artifactId>maven-javadoc-plugin</artifactId><配置><additionalparam>-Xdoclint:none</additionalparam></配置></插件></插件>

关于参数描述中的 标签,我也看到了.看起来 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. I don't know.

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.

UPDATE 2019-04-19

Parts of the problems mentioned above has been fixed in JDK-8072052 : <dd> part of <dl> list in javadoc should not be in monospace font. Fixed in Java 9 onwards, not backported to Java 8.

解决方案

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:找回 JDK7 寻找 javadoc的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!

查看全文
登录 关闭
扫码关注1秒登录
发送“验证码”获取 | 15天全站免登陆