JDK8:取回javadoc的JDK7外观

内容来源于 Stack Overflow,并遵循CC BY-SA 3.0许可协议进行翻译与使用

  • 回答 (2)
  • 关注 (0)
  • 查看 (118)

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

JDK7:

JDK8:

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:

接下来,尝试在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:

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

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

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

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

提问于
用户回答回答于

您可以得到标准的JDK 8。,然后您可以将其放入某个源文件夹中,并告诉javadoc将其与其一起使用。选择。问题是没有向后兼容性保证,生成的HTML有时会发生很大的变化。这种情况发生在JDK 7上,现在发生在JDK 8上。然后,您还常常不得不考虑,仅仅因为JDK 8已经过时,有些人可能会使用JDK 7构建您的项目...

无论如何,我所做的是检测我们是否正在jdk 8或更高版本下构建,在这种情况下,我已经将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,:])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,不要忘记解决)。

我使用regexp的原因是希望它将能够在HTML和标准CSS中幸存下来...但是也许我应该只使用产生的CSS,我不知道。或者我应该选择使用大约第三的派对文档,这样我就可以控制使用的版本了。

用户回答回答于

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

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

然后,可以使用stylesheetfilejavadoc命令行或ant或maven中的属性

从命令行:

%javadoc -stylesheetfile <path> ...

在ant中:

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

斯蒂芬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中的参数描述现在总是等宽的,所以你不再需要代码标签了?

扫码关注云+社区