快捷搜索:  as  test  1111  test aNd 8=8  test++aNd+8=8  as++aNd+8=8  as aNd 8=8

游艇会线路检查中心:PHPDoc风格的注释



我们开拓的所有类都邑应用PHPDoc风格的注释,这样就能很轻易地为所有类构建API文档。PHPDoc建立在Sun公司的Javadoc系统根基之上,这是一种为所有函数、参数、变量和包加注释的简单措施,以便于开拓职员轻松地重用这游艇会线路检查中心些函数、参数、变量和包。

只管这一点对付这个Web利用的开拓并不太紧张,但开拓历程中应用这种风格的游艇会线路检查中心注释是一个好习气。别的,查看本书中的代码示例时你会发明,每个函数前面有一个PHPDoc注释块确凿很有用。

评释

本书中列出的代码平日不包孕PHPDoc注释,由于在正文中会对这些代码做具体的解释和阐明。不过,这个Web利用的下载代码中会尽可能包孕PHPDoc注释。

PHPDoc的做法是在每个函数、类或变量定义前放置一个注释块。并不是所有环境下都要求如斯,只是在需要的环境下才游艇会线路检查中心这么做。

每个注释块最前面是一个描述,然后是一个或多个可选的参数。例如,向一个函数增添PHPDoc注释时,可以指定输入参数和返回值数据。显然,为变量定义所编写的PHPDoc注释则包孕不合的信息。

以下代码显示了为一个简单的用户自定义函数编写PHPDoc注释的例子:

首先要留意注释块若何开始。/**唆使PHPDoc解析器一个PHPDoc注释已经开始。

注释块的第一行是一个简短的描述。我小我的喜爱是在此只写函数、类或变量的名。

注释块中下一部分是一个对照长的描述。在这里我会尽力以一种黑盒的不雅点描述函数、类或变量的感化。也便是说,它会做什么,而不是它如何做。所有详细的功能或复杂的逻辑都由代码中的标准注释来解释。

评释

只管不是必需的,不过平日的约定是在/** … */块每行肇端处包孕一个星号。这主如果为了前进可读性,还能轻易地发明全部PHPDoc块。

注释块中着末一部分包孕各个PHPDoc参数,解析器用这些参数来更好地链接API文档,从而为你供给实用的文档。每个参数最前面是一个@,后面紧随着参数名,然后是该参数所需的信息。

这个例子中可以看到@param和@return参数。@param用于指定函数参数的各个方面:首先是参数的类型(在游艇会线路检查中心这里,第一个参数是一个字符串);接下来是参数名(这里是$name);着末是一个简短的描述,阐明输入的数据该当包孕哪些内容。@return参数用于游艇会线路检查中心供给函数所返回数据的有关信息:先指定命据的类型,然后是返回数据所包孕内容的一个简短描述。

免责声明:以上内容源自网络,版权归原作者所有,如有侵犯您的原创版权请告知,我们将尽快删除相关内容。

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