关键字: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