Introduction to Documentation Blocks

Documentation blocks (docblocks) are structured comments that provide information about code elements such as functions, classes, methods, and properties. They serve as a crucial bridge between code authors and users, making code more maintainable and accessible.

In this comprehensive guide, we'll explore three major documentation systems:

• PHPDoc - The standard for documenting PHP code
• JSDoc - The documentation system for JavaScript
• TSDoc - TypeScript's documentation convention

We'll cover syntax, common tags, best practices, and tools to help you create clear, consistent, and helpful documentation for your code.

Why Good Documentation Matters

Well-formatted documentation blocks provide numerous benefits:

• Code Understanding - Helps developers quickly grasp what code does without diving into implementation details
• API Documentation - Automatically generates comprehensive API documentation
• IDE Support - Enables intelligent code completion, type checking, and inline help
• Maintainability - Makes code easier to maintain, especially for new team members
• Reduced Bugs - Clear parameter and return type documentation helps prevent misuse

Investing time in proper documentation pays dividends throughout the lifecycle of your project.

PHPDoc Formatting

PHPDoc is the documentation standard for PHP code, inspired by JavaDoc. It uses structured comments to document classes, methods, functions, properties, and more.

PHPDoc Syntax Basics

PHPDoc blocks start with /** and end with{" "} */. Each line within the block typically begins with an asterisk *:

/**
 * This is a PHPDoc block
 */

The first line usually contains a short description. After a blank line, you can add a longer description, followed by tags that start with @:

/**
 * Short description of the function
 *
 * This is a longer description that can span
 * multiple lines and provide more detailed information
 * about what the function does.
 *
 * @param string $name The name parameter
 * @return string The formatted greeting
 */
function greet(string $name): string
{
    return "Hello, {$name}!";
}

Common PHPDoc Tags

PHPDoc uses a variety of tags to provide structured information:

/**
 * @param type $paramName Description
 * @return type Description
 * @throws ExceptionType Description
 * @var type Description (for properties)
 * @author Name 
 * @since Version
 * @deprecated Version Reason for deprecation
 * @see Reference
 * @link URL
 * @method returnType methodName(paramType $paramName) Description
 * @property type $propertyName Description
 * @property-read type $propertyName Description
 * @property-write type $propertyName Description
 */

PHPDoc Examples

Here are some real-world examples of PHPDoc in action:

JSDoc Formatting

JSDoc is the standard documentation system for JavaScript code. It helps document functions, classes, methods, and more, while also providing type information in plain JavaScript.

JSDoc Syntax Basics

Like PHPDoc, JSDoc blocks start with /** and end with{" "} */:

/**
 * This is a JSDoc block
 */

The structure is similar to PHPDoc, with a short description, optional long description, and tags:

/**
 * Calculates the sum of two numbers
 *
 * This function takes two numbers as input and returns their sum.
 * It performs basic error checking to ensure inputs are valid numbers.
 *
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 * @throws {TypeError} If either parameter is not a number
 */
function add(a, b) {
    if (typeof a !== 'number' || typeof b !== 'number') {
        throw new TypeError('Parameters must be numbers');
    }
    return a + b;
}

Common JSDoc Tags

JSDoc provides a rich set of tags for documenting JavaScript code:

/**
 * @param {type} paramName - Description
 * @returns {type} Description
 * @throws {ErrorType} Description
 * @type {type} Description (for variables)
 * @author Name
 * @since Version
 * @deprecated Reason for deprecation
 * @see Reference
 * @link URL
 * @example
 * // Example code here
 * @async
 * @generator
 * @yields {type} Description
 * @private
 * @public
 * @readonly
 * @typedef {type} TypeName
 * @property {type} propertyName Description
 */

JSDoc Examples

Here are some practical examples of JSDoc:

TSDoc Formatting

TSDoc is a documentation standard specifically designed for TypeScript. It builds on JSDoc but is tailored to work well with TypeScript's type system.

TSDoc Syntax Basics

TSDoc follows the same basic structure as JSDoc, but with some TypeScript-specific enhancements:

/**
 * This is a TSDoc block
 */

The main difference is that TSDoc can leverage TypeScript's type annotations, reducing the need for explicit type documentation in some cases:

/**
 * Calculates the sum of two numbers
 *
 * @param a - The first number
 * @param b - The second number
 * @returns The sum of a and b
 */
function add(a: number, b: number): number {
    return a + b;
}

Notice that we don't need to specify types in the{" "} @param and @returns tags because TypeScript already provides that information.

Common TSDoc Tags

TSDoc supports most JSDoc tags, with some additions and modifications:

/**
 * @param paramName - Description
 * @returns Description
 * @throws Description
 * @defaultValue Description
 * @remarks Additional detailed information
 * @example Example usage
 * @beta Feature is in beta stage
 * @alpha Feature is in alpha stage
 * @internal For internal use only
 * @sealed Class cannot be inherited from
 * @override Method overrides a parent method
 */

TSDoc Examples

Here are some examples of TSDoc in action:

Documentation Tools & Formatters

Various tools can help you generate, validate, and format documentation blocks.

PHP Documentation Tools

• phpDocumentor - The standard tool for generating documentation from PHPDoc blocks
• PHP_CodeSniffer - Can check and enforce PHPDoc formatting standards
• Doctum - A modern API documentation generator for PHP projects
• ApiGen - Another PHP documentation generator with a clean output

# Install phpDocumentor
composer require --dev phpdocumentor/phpdocumentor

# Install PHP_CodeSniffer
composer require --dev squizlabs/php_codesniffer

# Generate documentation
./vendor/bin/phpdoc -d src/ -t docs/

JavaScript & TypeScript Tools

• JSDoc - The standard documentation generator for JavaScript
• TypeDoc - Documentation generator for TypeScript projects
• ESLint with eslint-plugin-jsdoc - Lints and validates JSDoc comments
• DocumentThis - VS Code extension for automatically generating documentation
• API Extractor - Microsoft's tool for extracting API documentation from TypeScript

# Install JSDoc
npm install --save-dev jsdoc

# Install TypeDoc
npm install --save-dev typedoc

# Install ESLint with JSDoc plugin
npm install --save-dev eslint eslint-plugin-jsdoc

# Generate documentation
npx jsdoc src/ -d docs/
# or for TypeScript
npx typedoc src/

IDE Integration

Modern IDEs provide excellent support for documentation blocks, making it easier to write and maintain them.

Visual Studio Code

VS Code offers several extensions for working with documentation blocks:

• PHP DocBlocker - Provides automatic PHPDoc block generation
• Document This - Automatically generates JSDoc/TSDoc comments
• Better Comments - Improves the readability of comments
• ESLint with JSDoc plugins - Validates documentation

VS Code also provides built-in support for JSDoc and TSDoc, showing documentation when hovering over functions and providing autocomplete for tags.

PhpStorm

PhpStorm has excellent built-in support for PHPDoc:

• Automatic PHPDoc block generation (type /** above a function and press Enter)
• Code completion for PHPDoc tags
• Type inference based on PHPDoc annotations
• Documentation preview on hover
• Validation of PHPDoc blocks

WebStorm

WebStorm provides similar features for JSDoc and TSDoc:

• Automatic JSDoc/TSDoc block generation
• Code completion for documentation tags
• Type checking based on JSDoc annotations
• Documentation preview on hover
• Integration with ESLint for JSDoc validation

Documentation Best Practices

Follow these best practices to create effective documentation blocks:

1. Be consistent - Use the same style and format throughout your codebase
2. Document public APIs thoroughly - Public methods and functions should always be documented
3. Keep descriptions clear and concise - Avoid unnecessary verbosity
4. Include examples - Provide usage examples for complex functions
5. Document parameters and return values - Always specify what goes in and what comes out
6. Document exceptions and errors - Note when and why functions might throw exceptions
7. Update documentation when code changes - Outdated documentation is worse than no documentation
8. Use proper grammar and spelling - Professional documentation reflects well on your code
9. Document "why" not just "what" - Explain the reasoning behind complex code
10. Automate documentation checks - Use linters and CI/CD to enforce documentation standards

Conclusion

Well-formatted documentation blocks are essential for creating maintainable, accessible code. Whether you're working with PHP, JavaScript, or TypeScript, investing time in proper documentation pays dividends in code quality, developer onboarding, and long-term maintainability.

By following the guidelines and best practices outlined in this article, you can create documentation that serves as a valuable resource for your team and future developers who work with your code.

Remember that good documentation is not an afterthought—it's an integral part of the development process that should evolve alongside your code.