Wallogit.com
2017 © Pedro Peláez
The primary way of documenting a Rust project is through annotating the source code. These annotations can be viewed as part of the documentation, but they can also be compiled and executed. They call that "documentation as tests" and their documentation is a goldmine., (*1)
Rusty is an attempt at implementing the same idea in the PHP world., (*2)
Rusty is able to extract code samples from both PHP doc-blocks and Markdown files (your documentation for instance)., (*3)
An executable is provided to analyse the code samples scattered in your documentation and in your doc-blocks:, (*4)
rusty check -v ./src/
A code sample usually looks like this:, (*5)
/**
* Computes the n-th Fibonacci's number.
*
* Examples:
*
* ```
* assert(fibonacci(1) === 1);
* assert(fibonacci(2) === 1);
* assert(fibonacci(12) === 144);
* ```
*
* ```should_throw
* // -1 is invalid, some kind of error is expected
* fibonacci(-1);
* ```
*
* ```no_execute
* // it would take too much time to compute, we don't want to wait that long.
* fibonacci(10000);
* ```
*/
function fibonacci($n)
{
if ($n < 0) {
throw new \DomainException();
}
return $n <= 2 ? 1 : fibonacci($n - 1) + fibonacci($n - 2);
}
More examples can be found in the ./examples
directory., (*6)
Use rusty help check for a list of all the possible options., (*7)
Rusty can either be installed globally:, (*8)
composer global require kphoen/rusty dev-master
Or locally:, (*9)
composer require kphoen/rusty dev-master
Both methods will provide the rusty executable., (*10)
This library is under the MIT license., (*11)
MIT