Search code examples
phpdocumentationphpdoc

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

Things seem quite visually and machine-parseably clear with just /*

https://phpdoc.org/docs/latest/getting-started/your-first-set-of-documentation.html should say something about this, but doesn't.

Your thoughts?

Solution

  • 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:

    <?php
 /**
  * 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.