Often Raku modules authors would start a documentation with something like this:
# this module exposes a function named `func`
# and this function does so and so
my $a = func("a","b","c");
Minimal module documentation usually has a code example of how to use a module and run some basic stuff … The problem is however that sometimes this code example is erroneous, outdated or just does not work … Well, good-doc plugin deals with it!
Good enough documentation
I’ve recently added an experimental plugin to address valid documentation examples issue, it does exactly what is supposed to:
- Parse module’s README.md file
- Extract the very first code snippet (Raku code)
- And, finally execute it
Any case any errors occur during the last step, a warning message is printed out and an entire build is marked as having some warnings:
Following is an example of how to use the good-doc plugin within a SparrowCI pipeline:
zef install . --/test
zef test .
As usually I’d like to hear comments if such an experimental feature will be useful for users?