Support doctest

[munificent]

@liudonghua123 commented on Wed Jun 03 2020

I used doctest in python (https://docs.python.org/3/library/doctest.html), javascript (https://github.com/davidchambers/doctest, https://github.com/azu/power-doctest). That's really nice features. You can embed the test cases in your comments, and it is easy and quick for testing and show usage.

I'd like to vote up this feature in dart.

The following are some code snippets for demonstration.

• Python, examples from https://docs.python.org/3/library/doctest.html

"""
This is the "example" module.

The example module supplies one function, factorial().  For example,

>>> factorial(5)
120
"""

def factorial(n):
    """Return the factorial of n, an exact integer >= 0.

    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> factorial(30)
    265252859812191058636308480000000
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n must be >= 0

    Factorials of floats are OK, but the float must be an exact integer:
    >>> factorial(30.1)
    Traceback (most recent call last):
        ...
    ValueError: n must be exact integer
    >>> factorial(30.0)
    265252859812191058636308480000000

    It must also not be ridiculously large:
    >>> factorial(1e100)
    Traceback (most recent call last):
        ...
    OverflowError: n too large
    """

    import math
    if not n >= 0:
        raise ValueError("n must be >= 0")
    if math.floor(n) != n:
        raise ValueError("n must be exact integer")
    if n+1 == n:  # catch a value like 1e300
        raise OverflowError("n too large")
    result = 1
    factor = 2
    while factor <= n:
        result *= factor
        factor += 1
    return result


if __name__ == "__main__":
    import doctest
    doctest.testmod()

• Javascript, examples from https://github.com/davidchambers/doctest

// toFahrenheit :: Number -> Number
//
// Convert degrees Celsius to degrees Fahrenheit.
//
// > toFahrenheit(0)
// 32
// > toFahrenheit(100)
// 212
function toFahrenheit(degreesCelsius) {
  return degreesCelsius * 9 / 5 + 32;
}

[jcollins-g]

@munificent @stereotype441

Given that dart has no interactive mode we'd have to do something interesting here, perhaps, making up some interactive-like syntax that would trigger this similar to the javascript version. I'm not sure dartdoc is the right place for the implementation but I'm OK with the bug living here until there's a better place. I say this because I don't see the proposed program needing dartdoc's documentation inheritance/canonicalization or rendering features (indeed, they'd probably get in the way) -- a direct analyzer client with a code generator might be the way to go here.

[munificent]

I'm OK with the bug living here until there's a better place.

Thanks, I wasn't sure where to put it. It's definitely not a language issue. :)

[theRookieCoder]

Given that dart has no interactive mode we'd have to do something interesting here

Rust has doctests and like Dart, Rust has no interactive mode. I don't know how Rust's doctests work but we might be able to take inspiration from their implementation.

I second this feature as its a great way to easily write tests for functions, and it forces developers to provide examples for their functions/methods.