rspec/rules/S1176/php/rule.adoc

== Why is this an issue?

Try to imagine using a standard library without documentation.

It would be a nightmare, because documentation is the only way to understand of the contract of the API. Documenting an API  increases the productivity of the developers consuming it.


=== Noncompliant code example

[source,php]
----
<?php  // Noncompliant; file comment missing
class MyClass   // Noncompliant; undocumented
{

  $prop; // Noncompliant

  /**
   * Variable comment.
   */
  $prop2;  // Noncompliant; variable comment present, but @var tag missing

  protected $name, $description;  // Noncompliant

  function doSomething($param)  // Noncompliant
  {
    // ...
    if ($vogons) {
        throw new Exception('Help!.');
    }

    return 42;
  }
}
----

=== Compliant solution

[source,php]
----
<?php
/**
 * This is a file comment. There is vertical whitespace 
 * between it and the next element.
 */

/** 
 * MyClass does something interesting...
 */
class MyClass
{
  /**
   * Holds the vault combination
   * @var string 
   */
  $prop;

  /**
   * Variable comment.
   * @var number
   */
  $prop2;

  /** 
   *  @var string $name
   *  @var string $description
   */
  protected $name, $description;

  /**
   * Calculates the answer to a question
   *
   * @param string   The question
   *
   * @throws exception  If Vogons encountered
   *
   * @return integer  Returns the answer to life, the universe and everything
   */
  function doSomething($param)  // Noncompliant
  {
    // ...
    if ($vogons) {
        throw new Exception('Help!.');
    }

    return 42;
  }
}
----

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

* Add the missing documentation for this (file|class|function|variable).
* Add the missing "@return" tag for this function.
* Add the missing "@throws" tag for this function.
* Add the missing "@param" tag for "XXX".
* Add the missing "@var" tag for this variable.


=== Parameters

.file
****

----
true
----

Require documentation of files
****
.class
****

----
true
----

Require documentation of classes
****
.function
****

----
true
----

Require documentation of functions
****
.throws_tag
****

----
true
----

Require an "@throws" tag where appropriate
****
.return_tag
****

----
true
----

Require an "@return" tag
****
.param_tag
****

----
true
----

Require an "@param" tag for each function parameter
****
.variables
****

----
true
----

Require documentation of variables
****
.var_tag
****

----
true
----

Require that variable documentation contain an "@var" tag
****


'''
== Comments And Links
(visible only on this page)

include::../comments-and-links.adoc[]

endif::env-github,rspecator-view[]