Test file for checking which Squiz.Commenting rules to ignore.

commenting.php

<?php
/**
 * Summary (no period for file headers)
 *
 * Description (use period).
 *
 * @link http://example.com
 * @since 5.0.0
 *
 * @package WordPress
 * @subpackage Component
 */

/**
 * Summary.
 *
 * @since 5.0.0
 * @var string DEFINED_CONSTANT Description.
 */
define( 'DEFINED_CONSTANT', 'photomatt' );

/**
 * Summary.
 */
require_once( '/filename.php' );

/**
 * A class summary.
 *
 * @since 5.0.0
 *
 * @package WordPress
 * @subpackage Component
 */
class My_Class {
	/**
	 * Summary.
	 *
	 * @since 5.0.0
	 * @var string CONSTANT Description.
	 */
	const CONSTANT = 'ma.tt';

	/**
	 * Summary.
	 *
	 * @since 5.0.0
	 * @access public
	 *
	 * @var bool $some_variable
	 */
	public $some_variable;

	/**
	 * Summary.
	 *
	 * @todo Something that still needs to be done.
	 *
	 * @return bool
	 */
	public function some_function() {
		return true;
	}

	/**
	 * Summary.
	 *
	 * Longer description.
	 *
	 * @param mixed $some_var Some var description.
	 * @return null Returns early if not relevant, otherwise echo.
	 */
	public function another_function( $some_var = null ) {
		// Return early.
		if ( ! isset( $some_var ) ) {
			return;
		}

		// Do something.
		echo 'something';
	}

	/**
	 * Summary.
	 *
	 * Description.
	 *
	 * @since 5.0.0
	 * @access private
	 *
	 * @see bar()
	 * @link http://example.com
	 * @global WP_Post $post Description.
	 * @global WPDB $wpdb Description.
	 *
	 * @param int   $var Description.
	 * @param array $args {
	 *     Optional. An array of arguments.
	 *
	 *     @type int $number Description. Default 'value'. Accepts 'value', 'value'.
	 *                       (aligned with Description, if wraps to a new line)
	 *     @type bool $flag Description.
	 * }
	 * @return string Description.
	 */
	private function foo( $var, $args = array() ) {
		return '';
	}
}

/**
 * Summary.
 *
 * Description.
 *
 * @since 5.0.0
 * @access private
 *
 * @see My_Class::bar()
 * @link http://example.com
 * @global WP_Post $post Description.
 * @global WPDB $wpdb Description.
 *
 * @param int   $var Description.
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type int $number Description. Default 'value'. Accepts 'value', 'value'.
 *                       (aligned with Description, if wraps to a new line)
 *     @type bool $flag Description.
 * }
 * @return string Description.
 */
function bar( $var, $args = array() ) {
	// This is a single line comment.
	return '';
}

/**
 * Summary.
 *
 * Description.
 *
 * @since 5.0.0
 * @deprecated 5.0.0 Use {@see new_function_name()} instead.
 * @see new_function_name()
 *
 * @param int   $var Description.
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type int $number Description. Default 'value'. Accepts 'value', 'value'.
 *                       (aligned with Description, if wraps to a new line)
 *     @type bool $flag Description.
 * }
 * @return string Description.
 */
function deprecated( $var, $args = array() ) {
	/*
	 * This is a comment that is long enough to warrant being stretched over
	 * the span of multiple lines. You'll notice this follows basically
	 * the same format as the PHPDoc wrapping and comment block style.
	 */
	return '';
}

add_action( 'init', 'foobar_no_return' );
/**
 * Summary.
 *
 * @since 5.0.0
 */
function foobar_no_return() {

	/* translators: ... */
	echo esc_html__( 'foobar', 'domain' );

	/**
	 * Summary.
	 *
	 * Description.
	 *
	 * @since 5.0.0
	 *
	 * @param type  $var1 Description.
	 * @param array $args {
	 *     Short description about this hash.
	 *
	 *     @type type $var Description.
	 *     @type type $var Description.
	 * }
	 * @param type  $var2 Description.
	 */
	echo esc_html( apply_filters( 'foobar', $var1, $args, $var2 ) );

	/** This filter is documented in path/to/filename.php */
	echo esc_html( apply_filters( 'foobar', $var1, $args, $var2 ) );
}