51369b610e
When an include is not surrounded by empty lines, its content is inlined on the same line as the adjacent content. That can lead to broken tags and other display issues. This PR fixes all such includes and introduces a validation step that forbids introducing the same problem again.
189 lines
2.7 KiB
Plaintext
189 lines
2.7 KiB
Plaintext
== 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[]
|