思考了一晚上,写下总结,在此之前,需要读者读过《java核心技术 基础篇(第8版)》,在pdf版本150的页,如果你没有这本书,可以从这里下载,这是我的网盘百度云
其实虽然书中提到了很多知识点,不过还是有些需要动手去做才会发现问题,例如,我用intellij 14的文档生成器功能老是无法指定overview.html.最后不得已在命令行手动输入命令.
先列出我测试用的文件吧.
-
下面是目录
src文件夹里面有两个包,包里面各有包注释文档文件package-info.java,然后overview.html放在最外层.书上并没有说清楚如何指定overview.html,官方文档有提到,总之,执行如下命令就可以了(先进入src文件夹,并且我已经在src文件夹下创建了doc文件夹)javadoc -d doc/ aircraft/*.java vehicle/*.java -overview overview.html生成的格式和官方的在线API一模一样.
-
-overview选项
书上提到的内容比较少,我从官方的javadoc文档里补充一下把(自己翻译的).
每一个程序或一组包都可以有一个概述性的文档.在放源码文件中,javadoc会在运行时把他合入生成的网页中,你通常在这个文件里面放入用于描述整个程序或则一组包的文档.
创建一个overview注释文件,你可以给他任意命名,一般来说是overview.html,把他放置在任意地方,通常放在源文件的顶层树目录结构上.例如,java.applet包的源文件包含在C:\user\src\java\applet 目录中,你可以创建overview注释文件在C:\user\src\overview.html.
提示,在你想给同一组包中的不同文件运行多次javadoc时,你可以创建多个overview注释文件给同一组源文件,例如,你想运行带-private选项的javadoc来生成内部的文档,然后再次运行没有参数的javadoc来生成公共文档.在这种情况下,你就可以用在各自的overview注释文件中第一句来描述公共文档和内部文档.
overview注释文件的内容是总结式的注释,写在HTML文件中,就像之前提到package注释文件的那样,翻看那个描述来获取细节.再次复述,当写注释时,你应该让写一句关于整个程序或那组包的总结,不要放置一个标题或则别的内容.你可以把overview标签包含在内,与其他文档注释一样,放置的标签要是行内标签,例如{@link},必须出现在主要描述后面,如果你添加了一个@see 标签,那么它必须有一个完全限定(fully-qualified)的名字.
当你运行javadoc工具的时候,你需要用-overview选项来指定overview注释文件,这个文件的处理结果和package注释文件类似Each application or set of packages that you are documenting can have its own overview documentation comment, kept in its own "source" file, that the Javadoc tool will merge into the overview page that it generates. You typically include in this comment any documentation that applies to the entire application or set of packages.
To create an overview comment file, you can name the file anything you want, typically overview.html and place it anywhere, typically at the top level of the source tree. For example, if the source files for the java.applet package are contained in C:\user\src\java\applet directory, you could create an overview comment file at C:\user\src\overview.html.
Notice you can have multiple overview comment files for the same set of source files, in case you want to run javadoc multiple times on different sets of packages. For example, you could run javadoc once with -private for internal documentation and again without that option for public documentation. In this case, you could describe the documentation as public or internal in the first sentence of each overview comment file.
The content of the overview comment file is one big documentation comment, written in HTML, like the package comment file described previously. See that description for details. To re-iterate, when writing the comment, you should make the first sentence a summary about the application or set of packages, and not put a title or any other text between <body> and the first sentence. You can include overview tags; as with any documentation comment, all tags except in-line tags, such as {@link}, must appear after the main description. If you add a @see tag, it must have a fully-qualified name.
When you run the Javadoc tool, you specify the overview comment file name with the -overview option. The file is then processed similar to that of a package comment file. -
生成注释的类型
默认只生成用public和protected修饰符修饰的方法 变量 和类,文档有如下解释-public Shows only public classes and members.
-protected Shows only protected and public classes and members. This is the default.
-package Shows only package, protected, and public classes and members.
-private Shows all classes and members.
扫一扫
7497
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
