JDK8：取回javadoc的JDK7外观

2018-07-02 23:25:27

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

JDK7： JDK7 javadoc的样子

JDK8： JDK8 javadoc的样子

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

我最大的问题是在“参数”和“抛出”部分中，参数和描述之间不再有任何视觉差异。他们都在一个单一的间隔字体。我认为，用单间隔字体书写描述性文字只是丑陋的。单音间距字体是用于标识符名称，源代码列表等。（随意不同意）。

在仍然使用JDK8 javadoc工具的情况下，我可以获得JDK7风格吗？

我期待javadoc -stylesheet jdk7.css ，其中jdk7.css是jdk7.css包含的东西。另外，如果我决定自己定制css（不是我的东西，但可能没有其他解决方案），我不想在我们的企业中的每个构建服务器上确保新样式表的可用性。也许有一个Maven的解决方案呢？

可能的解决方案？

有人建议（下文）将JDK7 javadoc css与JDK8 javadoc工具一起使用，以查看是否会带回一些符合条件的Javadoc。

我通过检查Apache Commons Lang项目的源代码完成了我的测试。我只使用源代码，而不是他们的POM。这是为了确保我知道我在正确的基础上工作。

好的，首先 - 供参考 - 这里是由所有JDK7工具链（JDK7 javadoc工具，JDK7 css）生成的Javadoc。这是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>

和由此产生的Javadoc： JDK7 javadoc，JDK7 css

接下来，尝试在JDK8 javadoc工具中使用JDK7 css。这是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>

和由此产生的Javadoc： JDK8 javadoc，JDK7 css

所以，正如你所看到的，这个策略对我来说并不成功。

UPDATE

我刚意识到，这种变化的结果是，它已经成为没有意义的使用{@code }或<code> ）标记上的参数说明。反正它不显示。换句话说，如果你喜欢在过去这样做：

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

没有任何意义了。无论如何，你的null文本不会脱颖而出。

在Java 7的Javadoc中使用的CSS可以在这里找到：

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

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

从命令行：

%javadoc -stylesheetfile <path> ...

在蚂蚁中：

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

在Maven中（有关更多详细信息，请参阅Maven的样式表配置页面）：

<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有一篇关于在Java 8中对Javadoc的其他重大更改的文章。显然，doclint现在强制执行HTML 4合规性，并且在链接断开或不是100％正确的HTML 4时不会链接。您可以使用-Xdoclint:none作为附加参数将其关闭。

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

关于参数描述中的<code>标签，我也看到了。它看起来像javadoc中的参数描述现在总是等宽的，所以你不再需要代码标签了？

您可以获得标准的JDK 8 stylesheet.css并快速修复它，然后您可以将它放入某个源文件夹并告诉javadoc将其与stylesheetfile选项一起使用。问题在于没有后向兼容性保证，有时候生成的HTML会发生一些变化。这发生在JDK 7中，现在发生在JDK 8上。然后，您经常也必须考虑到，仅仅因为JDK 8出现问题，有些人可能会用JDK 7构建您的项目......

无论如何，我所做的是检测我们是否在JDK 8或更高版本下构建，并且在这种情况下，我已经在构建时在stylesheet.css上应用regexp替换。这对我来说很简单，因为这个旧项目使用Ant而不是Maven。只是想看看这些变化是什么，相关的部分是：

<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,:])serifb" 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,:])Arials*,s*Arialb" replace="Arial"
  />

  <!-- "Parameters:", "Returns:", "Throws:", "Since:", "See also:" etc. fixes: -->
  <property name="ddSelectorStart" value="(?:.contentContainers+.(?:details|description)|.serializedFormContainer)s+dls+ddb.*?{[^}]*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>

所以关键是上面的正则表达式，任何人都可以使用ant ， sed ，Notepad ++等（对于非Ant，不要忘记解析&...;和${...}部分）。

我使用正则表达式的原因是我希望它能够在HTML中进行一些更改，从而在标准CSS中生存......但也许我应该只使用生成的CSS，我不知道。或者我应该选择使用一些第三方doclet，因此我可以控制使用的版本。

我使用样式表来覆盖一些JDK8 CSS定义，使其看起来大多像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; }

我的Ant脚本命名原来stylesheet.css以stylesheetOrig.css和使用新版本（其中进口的原始版本）替代它：

<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>

链接地址: http://www.djcxy.com/p/91895.html

上一篇: JDK8: Getting back the JDK7 look for javadoc

下一篇: Internal working of ConcurrentHashMap?