Докблок

В программировании докблок указанный или DocBlock — это специально отформатированный комментарий, в исходном коде , который используется для документирования определенного сегмента кода. Это делает формат DocBlock независимым от целевого языка (при условии, что он поддерживает комментарии); однако это также может привести к появлению множества или противоречивых стандартов.

Примеры реализации

С#

/// <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;
}

Ява

/**
 * 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;
}

Питон

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;

Руби

##
# 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

Ржавчина

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

См. также

Docstring — энергонезависимая документация для конкретного языка.
Сравнение генераторов документации