php评论中额外星号的目的是什么？

I've (finally) been reading up on PEAR (php) coding standards.

我（最后）正在阅读PEAR（php）编码标准。

What is the purpose of commenting like this:

这样评论的目的是什么：

/** 
*   Here is my comment
*   I Wrote this in a haiku
*   But why put the stars?
*/

As opposed to this:

与此相反：

/* 
   Here is a comment
   No haiku or 
   anything special, but it still works!
*/

6 个解决方案

#1

The /** stuff */ document is also referred to as DocBlock notation.

/ ** stuff * / document也称为DocBlock表示法。

It's used to document PHP functions, classes, etc.

它用于记录PHP函数，类等。

/** 
* A test function
*
* @param  foo $bar
* @return baz
*/
function test(foo $bar) { return new baz; }

Some editors make good use of this to perform their Code Insight feature, a very powerful tool that reduces the time you have to spend looking at your old function declarations. Aptana and Zend Studio have this feature, probably others as well.

一些编辑很好地利用它来执行他们的Code Insight功能，这是一个非常强大的工具，可以减少您花在查看旧函数声明上的时间。 Aptana和Zend Studio有这个功能，也可能是其他功能。

You can also use it in combination with Reflection to do some sort of AOP, doing runtime inspection of the DocBlock above your declarations. In fact, Doctrine uses it to build an object attribute map for their "Active Record" implementation.

您还可以将它与Reflection结合使用来执行某种AOP，在声明之上对DocBlock进行运行时检查。事实上，Doctrine使用它为他们的“Active Record”实现构建一个对象属性映射。

#2

The double asterisk comment is used sometime by certain documentation systems. The documentation system will proccess the block and look for certain keywords like @author or @var.

某些文档系统有时会使用双星号注释。文档系统将处理该块并查找某些关键字，如@author或@var。

Single asterisk comments wil be treated as // comments.

单个星号注释将被视为//注释。

See PhpDoc http://www.phpdoc.org/docs/latest/guides/types.html

请参阅PhpDoc http://www.phpdoc.org/docs/latest/guides/types.html

#3

I agree with ajon and Quentin. Mainly it's readability. However,there is one more thing.

我同意ajon和Quentin。主要是它的可读性。但是，还有一件事。

There are automatic documentation generators (like doxygen ).

有自动文档生成器（如doxygen）。

They require some particular comment formatting to include these comments into documentation. I believe this style of commenting is used exactly for this purpose (look at following doxygen documentation page - http://www.stack.nl/~dimitri/doxygen/docblocks.html)

它们需要一些特定的注释格式才能将这些注释包含在文档中我相信这种评论方式完全用于此目的（请参阅以下doxygen文档页面 - http://www.stack.nl/~dimitri/doxygen/docblocks.html）

#4

Readability.

可读性。

It clearly highlights the commented section to people reading the code.

它清楚地突出了人们阅读代码的注释部分。

#5

I think it is mostly just for appearance/readability. Imagine you have a very long comment section that extends beyond one screen. Then seeing those asterisks lets you know it is part of a comment even if you can't see the beginning and end.

我认为这主要是为了外观/可读性。想象一下，你有一个很长的评论部分，它超出了一个屏幕。然后看到这些星号让你知道它是评论的一部分，即使你看不到开头和结尾。

#6

If you use the excellent free text editor jEdit for editing your PHP it highlights the code in different colours to show what is a verb, what is a variable etc.

如果您使用优秀的*文本编辑器jEdit来编辑PHP，它会突出显示不同颜色的代码，以显示动词是什么，变量是什么等。

If you comment out a block with /* ... */ everything inside the block goes orange, making it difficult to read the code.

如果用/ * ... *注释掉一个块，那么块内的所有内容都会变成橙色，这使得难以读取代码。

If you instead comment it out with /** ... */ then it changes everything in the block to a different set of colours that still highlight the different parts of the code, meaning the code remains very readable.

如果您使用/ ** ... * /注释掉它，那么它会将块中的所有内容更改为仍然突出显示代码不同部分的不同颜色集，这意味着代码仍然非常易读。

PS. If you use Notepad or similar to edit your PHP code then I strongly suggest that you get jEdit. It will save you a huge amount of time and frustration. Things like automatically indicating the start and end of { } , ( ) etc.

PS。如果您使用记事本或类似编辑PHP代码，我强烈建议您获得jEdit。它将为您节省大量时间和挫折感。像自动指示{}，（）等的开始和结束的事情。

#1