On 26/02/2016 04:51, Marvin Humphrey wrote:
Today, I read through all the documentation for the Clownfish runtime on
metacpan. It is truly gratifying to see all this work coming together.
For most of it, I read aloud so that I it would be hard to skip over any
problems. My impression overall was that the material was very accurate.
I found very few instances of documentation which I knew to be incorrect, and
I found only the smallest sampling of grammatical nits.
Thank you so much.
The only other item of interest was that some classes had an empty
DESCRIPTION. (String, ByteBuf, CharBuf...). This arises
whenever the class docucomment contains only a single sentence.
Right. This is occurred to me at some point, but I forgot to implement a fix.
I think we can live with these empty sections for now.
It's always a scalar at least. This could probably be named from the type.
It won't always be accurate (e.g. a Vector will be converted to native host
type, in this case a Perl array ref) and it will be weird if the return type
matches the type of the invocant (`my $hash = $hash->clone()`) but it's
probably worth the occasional weirdness over sticking with `my $retval = `
everywhere.
I went with the conservative approach, and used `$retval` for the return
value. I also changed the code samples for labeled parameters to derive
variable names from the parameter name instead of the type. This isn't as
descriptive but avoids any confusion about variable names.
I uploaded new dev releases for Clownfish and Lucy to CPAN (hopefully the last
ones). The Clownfish release includes your documentation fixes.
https://metacpan.org/release/NWELLNHOF/Clownfish-0.4.99_4
https://metacpan.org/release/NWELLNHOF/Lucy-0.4.99_2
Nick
