On Tue, Feb 23, 2016 at 5:38 AM, Nick Wellnhofer <[email protected]> wrote: > Lucifers, > > I uploaded previews of the upcoming 0.5.0 releases to CPAN. One of the major > changes in 0.5 is the generated documentation.
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. > Note that links in the documentation lead to the latest non-dev release > 0.4.4 and are broken for newly created modules and files. Ah. 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. > As you can see, required arguments and default values are documented > automatically. >From my perspective, the autogenerated code samples are shockingly good. :) I would have anticipated much more intractable problems. > One thing that's still missing is the return value. 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. > My current plan is to switch to the following naming scheme: > > my $retval = $searcher->hits( > query => $query, # required > offset => $offset, # default: 0 > num_wanted => $num_wanted, # default: 10 > sort_spec => $sort_spec, # default: undef > ); Looks fantastic! The generated POD for 0.5.0 will be *way* better than earlier releases. Marvin
