docstring conventions

python (google style):
  def function(param1: str, param2: int = 10) -> bool:
      """Brief description of function.

      longer description if needed. explains the purpose
      and any important details.

      Args:
          param1: description of param1
          param2: description of param2. defaults to 10.

      Returns:
          True if successful, False otherwise.

      Raises:
          ValueError: if param1 is empty.

      Example:
          >>> function("test", 5)
          True
      """

javascript (jsdoc):
  /**
   * brief description of function.
   *
   * @param {string} param1 - description
   * @param {number} [param2=10] - description (optional)
   * @returns {boolean} description
   * @throws {Error} when param1 is empty
   * @example
   * function("test", 5) // returns true
   */

