doc无法编译java文件_javadoc编译swing-worker-src-1.1.zip遇到的几个问题

关键字：javadoc

警告：编码 GBK 的不可映射字符

警告 - @Override 是未知标记

html中出现问号???的乱码

Tag @see cannot be used in inline documentation

最近研究SwingWorker，下载了swing-worker-doc-1.1.zip，但里面只有public类的文档，于是下载了swing-worker-src-1.1.zip，想通过javadoc得到package和private级别类的文档。

首先在NetBeans中创建Java Free-Form Project，工程名为SwingWorker，设置好source路径等，查看build.xml下有compile/javadoc/bundles等ANT build Target。然后开始编译，却遇到一系列的问题。

1)首先遇到的问题是运行compile遇到警告 AccumulativeRunnable.java:4: 警告：编码 GBK 的不可映射字符

原因是java文件开头的第4行(注释行)中出现了字符© (源文件中是单字节的0xA9)。这个字符是扩展ASCII码，不含在ascii编码中；含在iso-8859-1编码中，不含在GBK编码中。因此其encoding应该是iso-8859-1，不能是平台缺省的GBK，也不能是ASCII。

字符©虽然含在Unicode编码中，但是双字节编码，因此encoding也不能是unicode；字符©虽然含在UTF-8编码中，但编码不是单字节而是双字节 0xC2 0xA9(注意第二个字节也是0xA9)，因此encoding也不能是UTF-8；

以下是源代码的第4行：

* Copyright © 2005 Sun Microsystems, Inc. All rights

从以上分析得到解决办法：在target name="compile"的javac选项中加入：encoding="iso-8859-1"，警告不再出现。

2)开始运行javadoc，一样也遇到警告 AccumulativeRunnable.java:4: 警告：编码 GBK 的不可映射字符

解决办法同上，即在target name="javadoc"的javadoc选项中加入：encoding="iso-8859-1"，警告不再出现。

3)运行javadoc，遇到新警告 AccumulativeRunnable.java:75: 警告 - @Override 是未知标记

在文件第75行并没有发现有@Override－－实际上是从这行开始定义class AccumulativeRunnable的。后来看生成的html，发现类文档生成不全。这个文档中有类的使用举例，举例的代码行中有@Override。html中的类文档总是只包含了到第一个@Override之前行的内容。

据此猜测javadoc认为在注释中出现的@Override不合法，于是寻找javadoc中@的escape转义字符。试过了@@，不行。

后来找到

里面说用@来替代@。按照这个思路，发现用& #039;(去掉中间空格)就可以了，也就是将注释文档部分中的@Override修改为& #039;(去掉中间空格)Override，javadoc运行时就没有这个警告了。

4)html中出现问号???的乱码！如本该显示为"所有已实现的接口："(对应英文为"All Implemented Interfaces:")的，却显示为几个问号

尝试在javadoc ANT脚本中加入选项Locale="en_US"，得到了英文的html，显示是正常的。

继续尝试，找到解决办法：去掉前面提到的选项Locale，加入选项 docencoding="gbk" 即可得到中文显示正常的html文档。

在JDK javadoc文档中查-docencoding 的用法，提到：如果用了-encoding参数而省略了-docencoding参数，-docencoding就会缺省采用-encoding的设置。在本例中，如果我们不加-docencoding参数，则其缺省值就是iso-8859-1，而这个字符集是不支持汉字的。

[@more@]

到现在，最后还剩一个javadoc编译警告：AccumulativeRunnable.java:105: warning - Tag @see cannot be used in inline documentation. It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.

没有查到资料，就暂不解决了。

附上修改后的SwingWorker v1.1的源文件AccumulativeRunnable.java