快捷搜索:  as  2018  FtCWSyGV  С˵  test  xxx  Ψһ  w3viyKQx

澳门新葡亰平台app_龟发之家论坛



出自:www.csdn.net

对付Java说话,最体谅的一项设计便是它并没有盘算让人们为了写法度榜样而写法度榜样??人们也必要斟酌法度榜样的文档化问题。对付法度榜样的文档化,最大年夜的问题莫过于对文档的掩护。若文档与代码分离,那么每次改变代码后都要改变文档,这无疑会变成相称麻烦的一件工作。办理的措施看起来彷佛很简单:将代码同文档“链接”起来。为达到这个目的,最简单的措施是将所有内容都置于同一个文件。然而,为使统统都划一整洁,还必须应用一种特殊的注释语法,以便标记出特殊的文档;别的还必要一个对象,用于提取这些注澳门新葡亰平台app释,并按有代价的形式将其展现出来。这些都是Java必须做到的。

用于提取注释的对象叫作javadoc。它采纳了部分来自Java编译器的技巧,查找我们置入法度榜样的特殊注释标记。它不仅提取由这些标记唆使的信息,也将邻接注释的类名或措施名提掏出来。这样一来,我们就可用最轻的事情量,天生十分专业的法度榜样文档。

javadoc输出的是一个HTML文件,可用自己的Web浏览器查看。该对象容许我们创建和治理单个源文件,并活跃天生有用的文档。因为有了jvadoc,以是我们能够用标准的措施创建文档。而且因为它异常方便,以是我们能轻松得到所有Java库的文档。

2 详细语法

所有javadoc敕令都只能呈现于“/**”注释中。但和寻常一样,注释停止于一个“*/”。主要经由过程两种要领来应用javadoc:嵌入的HTML,或应用“文档标记”。此中,“文档标记”(Doc tags)是一些以“@”开首的敕令,置于注释行的肇端处(但前导的“*”会被轻忽)。

有三种类型的注释文档,它们对应于位于注释后面的元素:类、变量或者措施。也便是说,一个类注释恰恰位于一个类定义之前;变量注释恰恰位于变量定义之前;而一个措施定义恰恰位于一个措施定义的前面。如下面这个简单的例子所示:

/** 一个类注释 */

public class docTest {

/** 一个变量注释 */

public int i;

/** 一个措施注释 */

public void f() {}

}

留意javadoc只能为public(公共)和protected(受保护)成员处置惩罚注释文档。“private”(私有)和“友好”(详见5章)成员的注释会被轻忽,我们看不到任何输出(也可以用-private标记包括private成员)。这样做是有事理的澳门新葡亰平台app,由于只有public和protected成员才可在文件之外应用,这是客户法度榜样员的盼望澳门新葡亰平台app。然而,所有类注释都邑包孕到输出结果里澳门新葡亰平台app。

上述代码的输出是一个HTML文件,它与其他Java文档具有相同的标准款式。是以,用户会异常认识这种款式,可在您设计的类中方便地“周游”。设计法度榜样时,请务必斟酌输入上述代码,用javadoc处置惩罚一下,不雅看终极HTML文件的效果若何。

3 嵌入HTML

javadoc将HTML敕令通报给最毕天生的HTML文档。这便使我们能够充分使用HTML的伟大年夜威力。当然,我们的终极念头是款式化代码,不是为了哗众澳门新葡亰平台app取宠。下面列出一个例子:

/**

*

* System.out.println(new Date());

*

*/

亦可象在其他Web文档里那样运用HTML,对通俗文本进行款式化,使其更具条理、加倍美不雅:

/**

* 您以致可以插入一个列表:

*

*

项目一

*

项目二

*

项目三

*

*/

留意在文档注释中,位于一行最开首的星号会被javadoc丢弃。同时丢弃的还有前导空格。javadoc会对所有内容进行款式化,使其与标准的文档外不雅切合。不要将

这样的标题算作嵌入HTML应用,由于javadoc会插入自己的标题,我们给出的标题会与之矛盾触犯。

所有类型的注释文档??类、变量和措施??都支持嵌入HTML。

4 @see:引用其他类

所有三种类型的注释文档都可包孕@see标记,它容许我们引用其他类里的文档。对付这个标记,javadoc会天生响应的HTML,将其直接链接到其他文档。款式如下:

@see 类名

@see 完备类名

@see 完备类名

每一款式都邑在天生的文档里自动加入一个超链接的“See Also”(拜见)条款。留意javadoc不会反省我们指定的超链接,不会验证它们是否有效。

5 类文档标记

伴同嵌入HTML和@see引用,类文档还可以包括用于版本信息以及作者姓名的标记。类文档亦可用于“接口”目的(本书后面会具体解释)。

1. @version

款式如下:

@version 版本信息

此中,“版本信息”代表任何得当作为版本阐明的资料。若在javadoc敕令行应用了“-version”标记,就会从天生的HTML文档里提掏出版本信息。

2. @author

款式如下:

@author 作者信息

此中,“作者信息”包括您的姓名、电子函件地址或者其他任何合适的资料。若在javadoc敕令行应用了“-author”标记,就会专门从天生的HTML文档里提掏出作者信息。

可为一系列作者应用多个这样的标记,但它们必须继续放置。整个作者信息会一路存入终极HTML代码的零丁一个段落里。

6 变量文档标记

变量文档只能包括嵌入的HTML以及@see引用。

7 措施文档标记

除嵌入HTML和@see引用之外,措施还容许应用针对参数、返回值以及违例的文档标记。

1. @param

款式如下:

@param 参数名 阐明

此中,“参数名”是指参数列表内的标识符,而“阐明”代表一些可延续到后续行内的阐明翰墨。一旦碰到一个新文档标记,就觉得前一个阐明停止。可应用随意率性数量的阐明,每个参数一个。

2. @return

款式如下:

@return 阐明

此中,“阐明”是指返回值的含义。它可延续到后面的行内。

3. @exception

有关“违例”(Exception)的具体环境,我们会在第9章讲述。简言之,它们是一些特殊的工具,若某个措施掉败,就可将它们“扔出”工具。调用一个措施时,只管只有一个违例工具呈现,但一些特殊的措施大概能孕育发生随意率性数量的、不合类型的违例。所有这些违例都必要阐明。以是,违例标记的款式如下:

@exception 完备类名 阐明

此中,“完备类名”明确指定了一个违例类的名字,它是在其他某个地方定义好的。而“阐明”(同样可以延续到下面的行)奉告我们为什么这种特殊类型的违例会在措施调用中呈现。

4. @deprecated

这是Java 1.1的新特点。该标记用于指出一些旧功能已由改进过的新功能取代。该标记的感化是建议用户不必再应用一种特定的功能,由于未来改版时可能摒弃这一功能。若将一个措施标记为@deprecated,则应用该措施时会收到编译器的警告。

您可能还会对下面的文章感兴趣: