目录
如何文档化你的PHP类(二)
首页 php教程 php手册 如何文档化你的PHP类(二)

如何文档化你的PHP类(二)

Jun 21, 2016 am 08:58 AM
abstract nbsp php quot

如何文档化你的PHP类(二)

[br]
作者:stefano Locati 翻译:limodou  

文档化函数或方法  
  成员函数或方法使用@function标记被文档化。  

--------------------------------------------------------------------------------  
/*! @function getItemingroup  
    @abstract gets a bagitem of a given group and a given position  
    @param groupno int - the delivery group ordinal position in the bag  
    @param pos     int - the position of the bagitem within the group  
    @result Object - the BagItem in a given position of given group  
or -1 if it could not be found  
*/  
--------------------------------------------------------------------------------  

文档化一个方法。  

  @function标记声明了一个函数并且后面跟着函数或成员函数名。然后你可以象前面一样使用 @abstract和@discussion标记。然而还有两个额外的标记。@param标记用于描述函数的参数;第一个词假设为变量的名字,其它的则为任意的文本描述。我建议要声明想要的变量类型,尽管PHP不是一个强类型语言。 @result标记被用于描述返回值。  

文档化变量  
  变量或类变量都使用@var标记来描述。在这个标记中,第一个词被认为是变量的名字,同时其它的则为任意的文本描述。象前面一样,我建议写出所期望的变量类型是好的做法。它也是一个文档化所有类变量的好主意。  


文档化一个类变量。  

--------------------------------------------------------------------------------  
/*! @var idsession   string - an unique session identifier */  
var $idsession;  
--------------------------------------------------------------------------------  
最后接触  
--------------------------------------------------------------------------------  
/*! @header myprojectname  
    @abstract a virtual store to shop on mars  
    @discussion The difference [...]  
*/  
--------------------------------------------------------------------------------  
  @header标记用来提供一些关于被文档化的项目或类组的一般性信息。@header标记本身跟着项目的名字 ,而且可以用@abstract标记和@discussion标记来补充说明。因为类通常存在于不同的文件中(一个文件一个类,且用类的名字给文件名字是一种好的想法),你可能想知道应该将@header 标记放在什么地方。答案很让人吃惊,哪都可以。我的建议是:如果它比较长就把它放在一个独立的文件中,或如果是一个简短的说明就把它放在最重要的类的前面。  

如何修改脚本用于PHP  
  从Apple得到的初始的HeaderDoc脚本是用于C或C++头文件的,所以要用在PHP中需要对它做一些小改动 。如果你对细节没有兴趣,你可以从这里下 载,并且跳过下面部分。
  修改源程序所做的唯一的事情就是在主perl文件中,使脚本可以接受.php和.php3后缀。  

--------------------------------------------------------------------------------  
$ diff headerDoc2HTML.pl /usr/local/bin/headerdoc2html  
195c195  
---  
>     ($rootFileName = $filename) =~ s/.(h|i|php|php3)$//;  
--------------------------------------------------------------------------------  
运行脚本  
  在安装完脚本之后,假设你的类放在classes子目录下,并且你想将生成的文档放在docs目录下,你应该执行这个命令:  

headerdoc2html -o docs classes/*.php  

  不幸的是如果存在多个PHP文件,这个脚本有一个坏习惯就是将那些文件分割到不同的目录中去,使得在类的文档中浏览变得很困难。而且因为初始的脚本是为C/C++头文件所写的(头文件中只有类和函数的声明而没有他们的定义),脚本会将函数名下的所有代码输出,直到碰到";",所以典型的就是代码的第一行。  

  但是在你好不容易读到现在却感到绝望之前,放松,因为我写了一段简单的脚本来解决这两个问题。  

--------------------------------------------------------------------------------  
cat classes/*.php | sed 's/ *{/;#{/g' | tr "#" "  
" > docs/all.php  
headerdoc2html -o docs docs/all.php  
rm docs/all.php  
--------------------------------------------------------------------------------  
  如果你想知道为什么我在这里使用tr命令而不是都用sed来做,原因就是用在仍然用在RedHat 6.2上的sed 3.02版本不处理换行符。应该替换成新的版本sed 3.02a。如果你对sed感兴趣,可以看SED FAQ。  

  祝你的文档化工作好运!  

翻译后话:  
  由于这篇文章是在Linux环境下使用的,所以在windows下的使用可能会有问题。我会试一试,能想办法就想了,实在想不出来也没有办法了。  

原作者:limodou  
来源:PHPX   



本站声明
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

热AI工具

Undresser.AI Undress

Undresser.AI Undress

人工智能驱动的应用程序,用于创建逼真的裸体照片

AI Clothes Remover

AI Clothes Remover

用于从照片中去除衣服的在线人工智能工具。

Undress AI Tool

Undress AI Tool

免费脱衣服图片

Clothoff.io

Clothoff.io

AI脱衣机

Video Face Swap

Video Face Swap

使用我们完全免费的人工智能换脸工具轻松在任何视频中换脸!

热工具

记事本++7.3.1

记事本++7.3.1

好用且免费的代码编辑器

SublimeText3汉化版

SublimeText3汉化版

中文版,非常好用

禅工作室 13.0.1

禅工作室 13.0.1

功能强大的PHP集成开发环境

Dreamweaver CS6

Dreamweaver CS6

视觉化网页开发工具

SublimeText3 Mac版

SublimeText3 Mac版

神级代码编辑软件(SublimeText3)

适用于 Ubuntu 和 Debian 的 PHP 8.4 安装和升级指南 适用于 Ubuntu 和 Debian 的 PHP 8.4 安装和升级指南 Dec 24, 2024 pm 04:42 PM

PHP 8.4 带来了多项新功能、安全性改进和性能改进,同时弃用和删除了大量功能。 本指南介绍了如何在 Ubuntu、Debian 或其衍生版本上安装 PHP 8.4 或升级到 PHP 8.4

我后悔之前不知道的 7 个 PHP 函数 我后悔之前不知道的 7 个 PHP 函数 Nov 13, 2024 am 09:42 AM

如果您是一位经验丰富的 PHP 开发人员,您可能会感觉您已经在那里并且已经完成了。您已经开发了大量的应用程序,调试了数百万行代码,并调整了一堆脚本来实现操作

如何设置 Visual Studio Code (VS Code) 进行 PHP 开发 如何设置 Visual Studio Code (VS Code) 进行 PHP 开发 Dec 20, 2024 am 11:31 AM

Visual Studio Code,也称为 VS Code,是一个免费的源代码编辑器 - 或集成开发环境 (IDE) - 可用于所有主要操作系统。 VS Code 拥有针对多种编程语言的大量扩展,可以轻松编写

在PHP API中说明JSON Web令牌(JWT)及其用例。 在PHP API中说明JSON Web令牌(JWT)及其用例。 Apr 05, 2025 am 12:04 AM

JWT是一种基于JSON的开放标准,用于在各方之间安全地传输信息,主要用于身份验证和信息交换。1.JWT由Header、Payload和Signature三部分组成。2.JWT的工作原理包括生成JWT、验证JWT和解析Payload三个步骤。3.在PHP中使用JWT进行身份验证时,可以生成和验证JWT,并在高级用法中包含用户角色和权限信息。4.常见错误包括签名验证失败、令牌过期和Payload过大,调试技巧包括使用调试工具和日志记录。5.性能优化和最佳实践包括使用合适的签名算法、合理设置有效期、

您如何在PHP中解析和处理HTML/XML? 您如何在PHP中解析和处理HTML/XML? Feb 07, 2025 am 11:57 AM

本教程演示了如何使用PHP有效地处理XML文档。 XML(可扩展的标记语言)是一种用于人类可读性和机器解析的多功能文本标记语言。它通常用于数据存储

php程序在字符串中计数元音 php程序在字符串中计数元音 Feb 07, 2025 pm 12:12 PM

字符串是由字符组成的序列,包括字母、数字和符号。本教程将学习如何使用不同的方法在PHP中计算给定字符串中元音的数量。英语中的元音是a、e、i、o、u,它们可以是大写或小写。 什么是元音? 元音是代表特定语音的字母字符。英语中共有五个元音,包括大写和小写: a, e, i, o, u 示例 1 输入:字符串 = "Tutorialspoint" 输出:6 解释 字符串 "Tutorialspoint" 中的元音是 u、o、i、a、o、i。总共有 6 个元

解释PHP中的晚期静态绑定(静态::)。 解释PHP中的晚期静态绑定(静态::)。 Apr 03, 2025 am 12:04 AM

静态绑定(static::)在PHP中实现晚期静态绑定(LSB),允许在静态上下文中引用调用类而非定义类。1)解析过程在运行时进行,2)在继承关系中向上查找调用类,3)可能带来性能开销。

什么是PHP魔术方法(__ -construct,__destruct,__call,__get,__ set等)并提供用例? 什么是PHP魔术方法(__ -construct,__destruct,__call,__get,__ set等)并提供用例? Apr 03, 2025 am 12:03 AM

PHP的魔法方法有哪些?PHP的魔法方法包括:1.\_\_construct,用于初始化对象;2.\_\_destruct,用于清理资源;3.\_\_call,处理不存在的方法调用;4.\_\_get,实现动态属性访问;5.\_\_set,实现动态属性设置。这些方法在特定情况下自动调用,提升代码的灵活性和效率。

See all articles