That first "Ideal candidate criteria": "You have general familiarity with Perl conventions and “perlish documentation practices”"; could be a mistake.
Imagine if instead of this, you had something like:
my $mce = MCE->new(
max_workers => 8,
chunk_size => 2000,
tmp_dir => $tmp_dir,
freeze => \&encode_sereal,
thaw => \&decode_sereal,
gather => \@a,
init_relay => 0,
input_data => $input_file,
RS => "\n>",
use_slurpio => 1,
parallel_io => 1,
use_threads => 1,
spawn_delay => 0.035,
submit_delay => 0.002,
job_delay => 0.150,
on_post_exit => \&on_post_exit,
on_post_run => \&on_post_run,
user_args => { env => 'test' },
user_begin => \&user_begin,
user_func => \&user_func,
user_end => \&user_end,
user_error => \&user_error,
user_output => \&user_output,
stderr_file => 'err_file',
stdout_file => 'out_file',
flush_file => 1,
flush_stderr => 1,
flush_stdout => 1,
interval => { delay => 0.007 [, max_nodes => 4, node_id => 1 ]
+ },
sequence => { begin => -1, end => 1 [, step => 0.1 [, format =>
+"%4.1f" ] ] },
bounds_only => 1,
task_end => \&task_end,
task_name => 'string',
user_tasks => [ { ... }, { ... }, { ... },],
);
And when you mousever the keys, you get a brief explanation of the parameter; mouseover the value and the default is displayed; click the key and the embedded description comments from the original above are displayed in a popup.
Suddenly, those five screens worth of dense, complicated, hard-to-read details are all available on one screen, with a clear overview and a quick way to compare/contrast/lookup the details.
Apply that thinking through from the top level of the module.
Doesn't that seem a better way to both provide and explore the details of a complex module?
Is it too late to change “perlish documentation practices” for the better?
| 