更新2019-04-19

Question

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

JDK7： JDK7 javadoc look

JDK8： JDK8 javadoc look

JDK8占用了相当多的空间。它现在使用之前使用Arial的DejaVu字体。可能有充分的理由。说不上。

我最大的问题是在“参数”和“投掷”部分中，参数与其描述之间不再存在任何视觉差异。它们都是单声道间隔字体。我认为用单声道间隔字体书写描述性文字只是丑陋。单调间隔字体用于标识符，源代码列表等的名称。（随意不同意）。

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

我希望像javadoc -stylesheet jdk7.css这样的东西，其中jdk7.css包含在JDK8中。此外，如果我决定自己定制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

接下来，尝试将JDK7 css与JDK8 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.8.0_05/bin</javadocExecutable>   
            </configuration>
        </plugin>
    </plugins>
</build>

以及由此产生的Javadoc： JDK8 javadoc, JDK7 css

所以，正如你所看到的，这个策略对我没有用。

更新

我刚刚意识到这种变化的结果是在参数描述中使用{@code }（或<code>）标记变得毫无意义。它无论如何都没有显示出来。换句话说，如果你喜欢在过去喜欢这样做：

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

再也没有任何意义了。无论如何，您的null文字都不会突出。

更新2019-04-19

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

Answer 1

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

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

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

来自命令行：

%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作为附加参数将其关闭。< / p>

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

关于参数说明中的<code>标签，我确实也看到了这一点。看起来javadoc中的参数描述现在总是等宽的，所以你不再需要代码标签了吗？

Answer 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，不要忘记解析&...;和${...}部分）。

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

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

JDK8：获取javadoc的JDK7外观

可能的解决方案？

更新

更新2019-04-19

3 个答案: