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. With the exception of Lucy.pod,
every .pod file is now generated exclusively from Markdown sources! Please
have a look at the Lucy documentation and alert me if you find anything that's
broken:
https://metacpan.org/release/NWELLNHOF/Lucy-0.4.99_1
The Clownfish runtime is now fully documented. The class documentation isn't
very important for Perl users, but the files under Clownfish::Docs could need
some review:
https://metacpan.org/release/NWELLNHOF/Clownfish-0.4.99_3
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.
Clownfish::CFC is still undocumented for now.
Another important change is that the decision whether to document a method is
now based on the exposure specifier ("public") in the Clownfish header (.cfh)
files. Before, the set of documented methods was specified manually. This has
resulted in more complete documentation for some classes. Compare the
following files for example:
https://metacpan.org/pod/release/NWELLNHOF/Lucy-0.4.4/lib/Lucy/Analysis/Analyzer.pod
https://metacpan.org/pod/release/NWELLNHOF/Lucy-0.4.99_1/lib/Lucy/Analysis/Analyzer.pod
I also started to autogenerate code samples for every Perl method. For now,
they look like
$searcher->hits(
query => $obj, # required
offset => $int, # default: 0
num_wanted => $int, # default: 10
sort_spec => $sort_spec, # default: undef
);
As you can see, required arguments and default values are documented
automatically. One thing that's still missing is the return value. I'm also
thinking about a different naming scheme for the argument variables.
Currently, the name is based on the C type. One the one hand, this provides a
useful hint about the parameter type. On the other hand, this can be confusing
if the same variable name appears multiple times:
my $vector = $vector->clone();
my $int = $searcher->foo(
param1 => $int,
param2 => $int,
other => $searcher,
);
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
);
Nick
