Docblock

Short description: Specially formatted comment in source code

In programming, a docblock or DocBlock is a specially formatted comment specified in source code that is used to document a specific segment of code. This makes the DocBlock format independent of the target language (as long as it supports comments); however, it may also lead to multiple or inconsistent standards.

Implementation examples

C#

/// <summary>Adds two integers together.</summary>
/// <param name="a">First integer.</param>
/// <param name="b">Second integer.</param>
/// <returns>Sum of integers a and b.</returns>
int Sum(int a, int b)
{
    return a + b;
}

Java

/**
 * Adds two integers together
 * @param a First integer
 * @param b Second integer
 * @return Sum of integers a and b
 */
int sum(int a, int b)
{
    return a + b;
}

PHP

<?php
/**
 * Adds two integers together
 * @param int $a First integer
 * @param int $b Second integer
 * @return int Sum of integers $a and $b
 */
function sum(int $a, int $b): int
{
    return $a + $b;
}

Python

def sum(a: int, b: int) -> int
    """Adds two integers together.

    Args:
      a: First integer.
      b: Second integer.

    Returns:
      Sum of the two integers.
    """
    return a + b

JavaScript

/**
 * Adds two numbers together.
 * @param {number} a First number.
 * @param {number} b Second number.
 * @returns {number} Sum of numbers a and b
 */
 const add = (a, b) => a + b;

Ruby

##
# This class represents an arbitrary shape by a series of points.

class Shape

  ##
  # Creates a new shape described by a +polyline+.
  #
  # If the +polyline+ does not end at the same point it started at the
  # first pointed is copied and placed at the end of the line.
  #
  # An ArgumentError is raised if the line crosses itself, but shapes may
  # be concave.

  def initialize polyline
    # ...
  end

end

Rust

/// Adds two numbers together.
///
/// # Examples
///
/// ```
/// let result = sum(5, 5);
/// ```
fn sum(a: u64, b: u64) -> u64 {
    a + b
}

See also

• Docstring – Language-specific non-volatile documentation
• Comparison of documentation generators