include::../introduction.adoc[]

== Why is this an issue?

include::../why-is-this-an-issue.adoc[]

Try to imagine using a standard library without documentation.

It is recommended to document the API to clarify what is the contract of the API.
This is especially important for public APIs, as they are used by other developers.

== How to fix it

Add the missing documentation for the files, classes, functions and variables.

=== Code examples

==== Noncompliant code example

[source,php,diff-id=1,diff-type=noncompliant]
----
<?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,diff-id=1,diff-type=compliant]
----
<?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)
  {
    // ...
    if ($vogons) {
        throw new Exception('Help!.');
    }

    return 42;
  }
}
----

== Resources

=== Articles & blog posts

include::../articles-and-blog-posts.adoc[]


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[]