JDK8：找回 JDK7 查找 javadoc

Posted 2023-02-25

【中文标题】JDK8：找回 JDK7 查找 javadoc

【英文标题】：JDK8: Getting back the JDK7 look for javadoc

【发布时间】：2014-08-24 15:21:34

【问题描述】：

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

JDK7：

JDK8：

JDK8 占用了相当多的空间。它现在使用以前使用 Arial 的 DejaVu 字体。这可能有充分的理由。我不知道。

我最大的问题是在“参数”和“抛出”部分，参数与其描述之间不再有任何视觉差异。它们都是单行距字体。我认为，用单行距字体编写描述性文本很丑陋。 Mono 间隔字体用于标识符名称、源代码列表等。 （尽管不同意）。

我可以在使用 JDK8 javadoc 工具的同时恢复 JDK7 样式吗？

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

可能的解决方案？

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

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

好的，首先 - 供参考 - 这是由全 JDK7 工具链（JDK7 javadoc 工具，JDK7 css）生成的 Javadoc。这是 POM sn-p：

<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 css与JDK8 javadoc工具一起使用。这是 POM sn-p：

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

所以，如您所见，这个策略对我来说并不奏效。

更新

我刚刚意识到这种变化的结果是在参数描述上使用@code （或<code>）标记变得毫无意义。反正它不显示。换句话说，如果你过去喜欢这样做：

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

这根本没有意义。你的null 文字无论如何都不会突出。

2019 年 4 月 19 日更新

上面提到的部分问题已在JDK-8072052 : <dd> part of <dl> list in javadoc should not be in monospace font 中得到修复。在 Java 9 及更高版本中已修复，未向后移植到 Java 8。

【问题讨论】：

哇，8 的 javadoc 的可读性确实更差。对答案感兴趣。

@AndréStannek。不幸的是，你和我似乎是唯一这么认为的人。我没有在任何地方看到过这个，所以也许大多数人根本不在乎（或者认为这不重要）。令我震惊的是，为什么 JDK 开发人员积极地向后退了一步……在我看来。

猜这是一个见仁见智的问题，他们和我们一样有另一个:-(

伙计，在参数和 throws 上缺少缩进，另见部分是可怕的。

不需要“品味问题”和其他PC东西......因为很明显，他们刚刚跟随了非标准正面和“极简主义”的大字新趋势。在可读性方面，这绝不比 JDK7 中大小适中的 Arial 差。所以我想有人将不得不采用 JDK8 CSS 并对其进行修改。

【参考方案1】：

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

更新

Stephen Colebourne 有一篇关于 Java 8 here 中 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 中的参数描述现在总是等宽，所以你不再需要代码标签了？

【讨论】：

谢谢。我已经尝试过你的建议。不幸的是，简单地将 V7 css 与 V8 Javadoc 工具一起使用是行不通的。链接将丢失。视觉组件会重叠，等等。生成的 HTML 只是一团糟。这么多的希望。结论是您需要使用为您使用的 javadoc 工具版本制作的 css 文件。

@nolan6000 真的吗？它对我有用。我想我的 javadoc 库更容易渲染。缺少哪些链接？

查看我更新的问题，新部分名为“可能的解决方案？”。我做的和你不一样吗？

不确定我是否了解您的更新。我的印象是，doclint 与验证有关，而不是外观。而且由于这个问题是关于外观的，所以我看不到这种联系。关闭/打开 doclint 是否会改变生成结果的外观？如果我误解了你要去的地方，请告诉我。

您提到链接不起作用并且生成的 HTML 是一团糟，我认为这与 doclint 删除损坏的链接或弄乱标签有关。

【参考方案2】：

您可以获得标准的 JDK 8 stylesheet.css 并快速修复它，然后您可以将它放入某个源文件夹并告诉 javadoc 使用它的 stylesheetfile 选项。问题在于没有向后兼容性保证，生成的 HTML 有时会发生很大变化。 JDK 7 和现在 JDK 8 都发生了这种情况。然后您通常还必须考虑，仅仅因为 JDK 8 已经发布，有些人可能会使用 JDK 7 构建您的项目...

无论如何，我所做的是检测我们是否在 JDK 8 或更高版本下构建，在这种情况下，我在构建时对 stylesheet.css 应用了正则表达式替换。这对我来说很容易，因为这个旧项目使用的是 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,:])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>

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

我使用正则表达式的原因是我希望它能够在 HTML 和标准 CSS 中的一些变化中幸存下来......但也许我应该只使用生成的 CSS ， 我不知道。或者我应该选择使用一些 3rd 方 doclet，这样我就可以控制使用的版本。

【参考方案3】：

我使用样式表来覆盖一些 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>

【讨论】：

感谢分享。我也采取了同样的做法，即使用自定义样式表。因此，我们似乎都不得不使用 CSS 来解决 Java 8 中 JavaDoc 的可读性问题。可悲！