Daniel Rall wrote:
>> Log:
>> Adjust checkout() with named and optional parameter support.
>>
>> [in subversion/bindings/swig/perl/native]
>>
>> * Client.pm: Remove checkout from the list of general functions and
>> add it to the list of the functions that take named params. Provide
>> a Params::Validate parameter specification. Adjust the checkout
>> documentation accordingly.
>
> Nice log message.
Thanks.
> We typical list symbol names like this in the change log so that they're
> really obvious:
>
> * Client.pm
> (checkout): ...
OK. Will do from now on.
>> --- branches/perl-bindings-improvements/subversion/bindings/swig/perl/native/Client.pm (original)
>> +++ branches/perl-bindings-improvements/subversion/bindings/swig/perl/native/Client.pm Tue Jan 23 10:14:29 2007
> ...
>> @@ -312,7 +314,14 @@
>> other kind that requires a local path), then an error will be raised,
>> because the desired revision can not be determined.
>>
>> -=item $ctx-E<gt>checkout($url, $path, $revision, $recursive, $pool);
>> +=item $ctx-E<gt>checkout
>> +
>> + my $revision = $ctx->checkout({
>> + url => '...',
>> + path => '...',
>> + revision => $revision, # optional, default is 'HEAD'
>> + recurse => $recursive, # optional, default is 0
>> + });
> ...
>
> Any particular reason to remove the POD for the old calling style
> (e.g. named params are preferred)?
Partly that (I expect) named params will be preferred. Partly because I'm
slowly morphing the POD in to a different structure. In particular, I
expect that all these C<< =item >> entries are going to become C<< =head2 >>
entries. Many pod2... translators will then create ToC entries for them,
for example, and it keeps them cleaner.
There is a section earlier in the POD that explains that you can take named
params and convert them to positional params very easily.
Oh, and since I'm talking about the POD -- one thing that I'm toying with is
the idea that instead of having the POD in the .pm file be complete, we'll
have a build time processing step that will take the POD with some templated
sections, and automatically create some of the text for us.
Specifically, I'm aware that the POD for methods with named params
duplicates information that's already in the code. Following the general
DRY principle I'd like to put this info in one place (the method definition
hash), and generate POD from it automatically.
This would end up in a .pod file (e.g., SVN/Client.pod, generated from
SVN/Client.pm), and since perldoc(1) uses .pod files in preference to .pm
files the user will be shown the fleshed out documentation.
As I say -- an idea I'm toying with.
N
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Jan 24 11:18:00 2007