view raw
lkraav lkraav - 6 months ago 54
PHP Question

Why does phpDoc opening sequence have two stars in `/**` instead of just `/*`

Things seem quite visually and machine-parseably clear with just

/* should say something about this, but doesn't.

Your thoughts?


There is a difference between a regular php comment (/* ... */) and a DocBlock (/** ... */) (or PHPDoc).

PHP Interprets both as comments, however when using IDE's - they can parse the DocBlocks and provide you a better programming experience (with type-hints and autocomplets), and if you want you can use them to export a complete documentation of your code (packages/classes/functions/etc).

If you take for example this code:

  * A summary informing the user what the associated element does.
  * A *description*, that can span multiple lines, to go _in-depth_ into the details of this element
  * and to provide some background information or textual references.
  * @param string $myArgument With a *description* of this argument, these may also
  *    span multiple lines.
  * @return void
  function myFunction($myArgument)

You can see that the function myFunction doesn't return anything (@return void) and it only accepts one parameter ($myArgument) which supposed to be a string.

To export a complete documentation you can use the phpDocumentor tool.