PHP Doc Comments Adding Styles To Meta Box and Shortcode

Summary: Learning about PHP Doc comments, Adding Styles to Meta Box and Shortcode.

PHP Doc comments

Doc comments in PHP also known as PHPDoc are a way to document our code by adding structured comments that can be interpreted by IDEs, documentation generators, and other tools. These comments provide information about classes, methods, functions, properties, and more.

Basic Structure of a Doc Comment

A doc comment starts with /** and ends with */. Each line within the comment typically begins with an asterisk (*), though it is not required.

/**
 * This is a simple doc comment.
 */

Documenting Functions and Methods

When documenting functions or methods, doc comments usually describe the purpose of the function, its parameters, and the return value.

/**
 * Calculates the sum of two numbers.
 *
 * This method adds two integers and returns the result.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of $a and $b.
 */
function add($a, $b) {
    return $a + $b;
}

• Description: A brief explanation of what the function does.
• @param: Describes each parameter. The format is @param type $name Description.
• @return: Describes the return value. The format is @return type Description.

Documenting Classes

When documenting classes we typically describe the purpose of the class, any related classes, and list properties and methods.

/**
 * Represents a user in the system.
 *
 * This class is responsible for handling user-related data and operations.
 *
 * @property string $name The name of the user.
 * @property string $email The email of the user.
 */
class User {
    /**
     * The name of the user.
     *
     * @var string
     */
    private $name;

    /**
     * The email of the user.
     *
     * @var string
     */
    private $email;

    // Methods and other properties...
}

• Class Description: A general overview of the class and its responsibilities.
• @property: Documents class properties. The format is @property type $name Description.
• @var: Used inside the class to describe the type of properties.

Documenting Properties

For class properties, we use the @var tag within the doc comment to specify the type and provide a description.

/**
 * The age of the user.
 *
 * @var int
 */
public $age;

Adding Styles to Meta Boxes

function myplugin_enqueue_meta_box_styles() {
    wp_enqueue_style('myplugin-meta-box-styles', plugin_dir_url(__FILE__) . 'css/meta-box-styles.css');
}
add_action('admin_enqueue_scripts', 'myplugin_enqueue_meta_box_styles');

• wp_enqueue_style: This function enqueues a CSS file in WordPress.
• plugin_dir_url(__FILE__): Generates the URL to the directory where our plugin is located.

Adding Styles to Shortcodes

function myplugin_enqueue_shortcode_styles() {
    wp_enqueue_style('myplugin-shortcode-styles', plugin_dir_url(__FILE__) . 'css/shortcode-styles.css');
}
add_action('wp_enqueue_scripts', 'myplugin_enqueue_shortcode_styles');

• wp_enqueue_scripts: This hook is used to enqueue styles and scripts for the front end.
• shortcode-styles.css: This is where we would define the styles for your shortcodes.