requiredfixable
Ensure that all blocks have a docblock
Options
exclude
Exclude certain blocks from being checked
Type: array
Default: []
Possible values: class, interface, trait, property, method, function, constant
Examples
- Examples of correct code for this rule using default options
Class, interface, trait, properties and methods with docblock
php
<?php
/**
* Manage and handle database connections.
*/
class DatabaseConnect
{
/**
* @var int Minimum password length.
*/
private $min_password_length = 8;
/**
* @var int Maximum connections allowed
*/
private $max_connections = 10;
/**
* @var int Connection timeout in seconds
*/
private $connection_timeout = 30;
/**
* @var object Connection resource
*/
private $connection;
/**
* Connect to the database.
*
* @param string $host Hostname of the database server
* @param string $username Username to connect with
* @param string $password Password to connect with
* @param string $database Database to connect to
* @return bool True on success, false on failure
*/
public function connect($host, $username, $password, $database)
{
$this->connection = mysql_connect($host, $username, $password);
if (!$this->connection) {
return false;
}
if (!mysql_select_db($database, $this->connection)) {
return false;
}
return true;
}
}Constant variables and functions with docblock
php
<?php
/**
* @var string Key to use for API calls.
*/
const API_KEY = "IOPIQ345POL;2'3L4";
/**
* @var string API URL.
*/
const API_URL = "http://api.example.com";
/**
* @var string Used API version.
*/
const API_VERSION = "1.0.0";
/**
* @var int Timeout for API calls.
*/
const API_TIMEOUT = 30;
/**
* Get data from API endpoint.
*
* @param string $endpoint API endpoint
* @return string Data from API
*/
function getData($endpoint){
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, API_URL . $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, API_TIMEOUT);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"X-API-KEY: " . API_KEY,
"X-API-VERSION: " . API_VERSION
));
$data = curl_exec($ch);
curl_close($ch);
return $data;
}
/**
* Disconnect from database.
*/
function disconnect(){
echo "Disconnecting...";
}- Examples of incorrect code for this rule using default options
Control structures without docblock
php
<?php
class DatabaseConnect {
private $min_password_length = 8;
private $max_connections = 10;
private $connection_timeout = 30;
private $connection;
public function connect($host, $username, $password, $database) {
$this->connection = mysql_connect($host, $username, $password);
if (!$this->connection) {
return false;
}
if (!mysql_select_db($database, $this->connection)) {
return false;
}
return true;
}
}exclude
- Examples of correct code for this rule using exclude option
Exclude properties and methods from rule
php
<?php
/* taqwim "docblock/required": {exclude: ["property", "method"]} */
/**
* Manage and handle database connections.
*/
class DatabaseConnect {
private $min_password_length = 8;
private $max_connections = 10;
private $connection_timeout = 30;
private $connection;
public function connect($host, $username, $password, $database) {
$this->connection = mysql_connect($host, $username, $password);
if (!$this->connection) {
return false;
}
if (!mysql_select_db($database, $this->connection)) {
return false;
}
return true;
}
}Exclude constants and functions from rule
php
<?php
/* taqwim "docblock/required": {exclude: ["constant", "function"]} */
const API_KEY = "IOPIQ345POL;2'3L4";
const API_URL = "http://api.example.com";
const API_VERSION = "1.0.0";
const API_TIMEOUT = 30;
function getData($endpoint){
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, API_URL . $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, API_TIMEOUT);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"X-API-KEY: " . API_KEY,
"X-API-VERSION: " . API_VERSION
));
$data = curl_exec($ch);
curl_close($ch);
return $data;
}