tips:eclipse:autocomments
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
tips:eclipse:autocomments [2010/04/08 09:39] – created percy | tips:eclipse:autocomments [2016/05/05 13:07] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | 转一篇关于如何注释, | ||
+ | http:// | ||
+ | |||
+ | |||
+ | |||
+ | ====== 如何插入注释 ====== | ||
+ | |||
+ | |||
+ | JAVADOC为你生成代码不是凭空来的,也不是它会自动分析你的代码——每个人都有自己的代码风格,如果要进行分析翻译恐怕还是机器码更容易生成百倍。它的分析机制依赖于你按照规范为你的代码添加应有而足够的注释。只有你老老实实写注释,才有可能把以前需要做双份的工作一次做了。 | ||
+ | Javadoc工具可以从下列对象中提取出信息: | ||
+ | -包。 | ||
+ | -公共类。 | ||
+ | -公共接口。 | ||
+ | -公共或者受保护的方法。 | ||
+ | -公共或者受保护的变量/ | ||
+ | 针对每一种特性,你都应该提供一条注释。每一条注释都要以/ | ||
+ | 加入在注释中包含了指向其它文件的其它文件的链接的话(例如你的插图和图片),需要将那些文件放置在名为doc-files的子目录中。javadoc会将这些目录以及其中的文件从源目录复制到文档目录。下面我们分类解释一下我们可能会比较常用的一些标记。 | ||
+ | |||
+ | ====== 常规注释 ====== | ||
+ | |||
+ | 下面这些标记可以在所有文档注释中使用。 | ||
+ | ◇ @since 版本 | ||
+ | 该标记可以生成一个注释表明这个特性(类、接口、属性或者方法等)是在软件的哪个版本之后开始提供的。 | ||
+ | ◇ @deprecated 类、属性、方法名等 | ||
+ | 这个标记可以增加一条注释,指出相应的类、方法或者属性不再应该使用。javadoc仅将首句复制到概览部分和索引中。后面得句子还可以解释为什么不鼓励使用它。有时候,我们也推荐另外一种解决办法,例如: | ||
+ | @deprecated Use < | ||
+ | 或者使用{@link}标记给一个推荐的连接关于它的使用我们将马上介绍。 | ||
+ | ◇ @see 链接 | ||
+ | 这个标记在“See also”(参见)小节增加一个超链接。这里的链接可以是下面几项内容: | ||
+ | · package.class# | ||
+ | · <a href=...> | ||
+ | · " | ||
+ | ◇ {@link 链接目标 显示文字} | ||
+ | 其实准确的说,link的用法和see的用法是一样,see是把链接单列在参见项里,而link是在当前的注释中的任意位置直接嵌入一段带超级链接的文字。 | ||
+ | ====== 为类和接口添加注释 ====== | ||
+ | |||
+ | 类或者接口的注释必须在所有import语句的后面,同时又要位于class定义的前面。除了上面所说的常规标记以外,你还可以在类注释中使用如下标记: | ||
+ | ◇ @author 作者名 | ||
+ | 当使用author标记时,用指定的文本文字在生成的文档中添加“Author”(作者)项。文档注释可以包含多个@author标记。可以对每个 @author指定一个或者多个名字。当然你同样可以使用多个作者标记,但是它们必须放在一块儿。 | ||
+ | ◇ @version 版本 | ||
+ | 这个标记建议一个“版本”条目,后面的文字可以是当前版本的任意描述。 | ||
+ | 下面是类注释的一个例子: | ||
+ | |||
+ | |||
+ | |||
+ | < | ||
+ | /** | ||
+ | * An implementation of a menu bar. You add < | ||
+ | * menu bar to construct a menu. When the user selects a < | ||
+ | * object, its associated < | ||
+ | * user to select one of the < | ||
+ | * <p> | ||
+ | * For information and examples of using menu bars see | ||
+ | * <a | ||
+ | href=" | ||
+ | * a section in < | ||
+ | * For the keyboard keys used by this component in the standard Look and | ||
+ | * Feel (L&F) renditions, see the | ||
+ | * <a href=doc-files/ | ||
+ | * <p> | ||
+ | * < | ||
+ | * Serialized objects of this class will not be compatible with | ||
+ | * future Swing releases. The current serialization support is appropriate | ||
+ | * for short term storage or RMI between applications running the same | ||
+ | * version of Swing. A future release of Swing will provide support for | ||
+ | * long term persistence. | ||
+ | * | ||
+ | * @beaninfo | ||
+ | * attribute: isContainer true | ||
+ | * description: | ||
+ | * | ||
+ | * @version 1.85 04/06/00 | ||
+ | * @author Georges Saab | ||
+ | * @author David Karlton | ||
+ | * @author Arnaud Weber | ||
+ | * @see JMenu | ||
+ | * @see JPopupMenu | ||
+ | * @see JMenuItem | ||
+ | */ | ||
+ | </ | ||
+ | |||
+ | |||
+ | ====== 方法注释 ====== | ||
+ | |||
+ | 紧靠在每条方法注释的前面,必须有一个它所描述的那个方法的签名。同样除了使用常规用途的标记以外,还可以使用如下针对方法的注释: | ||
+ | ◇ @param 变量描述 | ||
+ | 当前方法需要的所有参数,都需要用这个标记进行解释,并且这些标记都应该放在一起。具体的描述(说明)可同时跨越多行,并且可以使用html标记。 | ||
+ | ◇ @return 该方法的返回值 | ||
+ | 这个标记为当前方法增加一个返回值(“Returns”)小节。同样具体描述支持html并可跨多行。 | ||
+ | ◇ @throws 该方法抛出的异常 | ||
+ | 这个标记为当前方法在“Throws”小节添加一个条目,并会自动创建一个超级链接。具体的描述可以跨越多行,同样可以包括html标记。一个方法的所有 throws都必须放在一起。 | ||
+ | 下面是一个方法注释的例子: | ||
+ | <code java> | ||
+ | /** | ||
+ | * Returns the model object that handles single selections. | ||
+ | * | ||
+ | * @param ui the new MenuBarUI L&F object | ||
+ | * @return the < | ||
+ | * @see SingleSelectionModel | ||
+ | * @see JComponent# | ||
+ | * @see UIDefaults# | ||
+ | */ | ||
+ | </ | ||
+ | |||
+ | ====== 包和综述注释 ====== | ||
+ | |||
+ | 前面的都是针对某一个类、方法等的注释,可以直接放在JAVA源文件中。然而为了生成一个包的注释,必须在每个包的目录下放置一个名为 package.html的文件来对包进行描述。标签< | ||
+ | 也可以为所有源文件提供一个综述注释,写入名为overview.html文件中,将其放在所有源文件所在的父目录下面。标签< | ||
+ | |||
+ | ====== 如何提取程序文档 ====== | ||
+ | |||
+ | |||
+ | 首先,我们还是依照惯例来看看javadoc的基本用法,你可以通过javadoc -help来获得它当前版本的具体设定细节。 | ||
+ | javadoc [options] [packagename] [sourcefiles] [@files] | ||
+ | 参数可以按造任意顺序排列。 | ||
+ | · options 命令行选项。 | ||
+ | · packagenames 一系列包的名字,空格分隔,必须分别制定想要为之建立文档的每一个包。Javadoc不递归作用于每一个包,也不允许使用通配符。 | ||
+ | · sourcefiles 一系列源文件名,用空格分隔。源文件名可以包括路径和通配符如“*”。 | ||
+ | · @files 以任意次序包含包名和源文件的一个或者多个文件。当在sourcefiles中需要指定的文件太多的时候,就可以使用它来简化操作。目标文件是以空格或者回车来进行分隔的源文件名。 | ||
+ | 其中常用的选项有: | ||
+ | -d 路径 | ||
+ | 指定javadoc保存生成的HTML文件的目的目录,缺省为当前目录。 | ||
+ | -author | ||
+ | 在文档中包含作者信息(默认情况下会被省略) | ||
+ | -version | ||
+ | 在文档中包含版本信息(在默认情况下会被省略) | ||
+ | -header header文本 | ||
+ | 指定放置在每个输出文件顶部的页眉文件。该页眉文件将放在上部导航栏的右边,header文本可以包括HTML标记和空格,但是如果这样就必须用引号将它括起。在header中的任何内部引号都不许使用转义。 | ||
+ | -footer footer文本 | ||
+ | 指定放置在每个输出文件底部的脚注文本。脚本将放置在下部导航栏的右边,其它同header一样。 | ||
+ | -bottom text | ||
+ | 指定放置在么个输出文件底部的文本。该文本将放置在页底,位于导航栏的下面。其它同header参数。 | ||
+ | -protected | ||
+ | 只显示受保护的和共有的类及成员,这是缺省状态。 | ||
+ | -public | ||
+ | 只显示公有的类和成员。 | ||
+ | -package | ||
+ | 只显示包、受保护的和公有的类及成员。 | ||
+ | -private | ||
+ | 显示所有的类和成员,如果是内部开发使用的程序文档,这个将非常有用。 | ||
+ | -sourcepath sourcepathlist | ||
+ | 当将包名传递给javadoc的时候,可以指定查找源文件(.java)的搜索路径。但必须注意,只有当用javadoc命令指定包名时才能使用 sourcepath选项。如果省略sourcepath,则javadoc使用classpath查找源文件。注意:你需要把sourcepath设置成目标包的源文件所在的目录,例如:你在从c: | ||
+ | -clathpath clathpathlist | ||
+ | 指定javadoc查找“引用类”的路径,“引用类”是值带文档的类加上它们引用的任何类。javadoc将搜索指定路径的所有子目录。 classpathlist可以包含多个路径,它们用分号分隔。 | ||
+ | |||
+ | 下面我们来举一个例子: | ||
+ | 假设,我们需要在targetdocdir放置我们生成的文档,需要对c: | ||
+ | |||
+ | 除了javadoc提供了丰富的选项参数来让你定制你所需要生成的程序文档以外,还可以借助doclet来产生任何形式的输出,具体的情况,请仔细阅读联机帮助文档。 | ||
+ | </ |