[
https://issues.apache.org/jira/browse/CLOWNFISH-64?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15054347#comment-15054347
]
ASF GitHub Bot commented on CLOWNFISH-64:
-----------------------------------------
GitHub user nwellnhof opened a pull request:
https://github.com/apache/lucy-clownfish/pull/49
CLOWNFISH-64 Autogenerate Perl subroutine code samples
Now the generated POD looks like
=head2 glean_query
$searcher->glean_query($query);
$searcher->glean_query(); # default: undef
[...]
=head2 hits
$searcher->hits(
query => $obj, # required
offset => $int, # default: 0
num_wanted => $int, # default: 10
sort_spec => $sort_spec, # default: undef
);
[...]
This also makes it possible to link to the POD section of a method or
constructor.
Having `$int` appear multiple times in the example above might be
confusing. Maybe the following more verbose format is better?
$searcher->hits(
query => $query, # Clownfish::Obj, required
offset => $offset, # integer, default: 0
num_wanted => $num_wanted, # integer, default: 10
sort_spec => $sort_spec, # Lucy::Search::SortSpec, default: undef
);
Other things that could be improved:
- Type information for positional parameters.
- Type information for return types.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/nwellnhof/lucy-clownfish
CLOWNFISH-64-autogenerate-code-samples
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/lucy-clownfish/pull/49.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #49
----
commit 5e7c5ceaa56e900417c67550fab2573598cb8eb4
Author: Nick Wellnhofer <[email protected]>
Date: 2015-12-12T14:34:03Z
Autogenerate Perl subroutine code samples
Resolves CLOWNFISH-64.
commit e2626d979b25c9a8f4bb8af9d48f104cdae99aeb
Author: Nick Wellnhofer <[email protected]>
Date: 2015-12-12T14:37:40Z
Remove argument summary from =head2 in POD
commit 18007a3a085fe51ebc12cd6b991770a0d6a17974
Author: Nick Wellnhofer <[email protected]>
Date: 2015-12-12T14:56:31Z
Make Clownfish URIs link to relevant POD section
----
> Autogenerate subroutine code samples in Perl POD
> ------------------------------------------------
>
> Key: CLOWNFISH-64
> URL: https://issues.apache.org/jira/browse/CLOWNFISH-64
> Project: Apache Lucy-Clownfish
> Issue Type: Improvement
> Components: Perl
> Reporter: Nick Wellnhofer
> Priority: Minor
>
> It should be possible to add autogenerated code samples for constructors and
> methods to the generated Perl POD. This would ensure that every subroutine
> has at least some rudimentary documentation of parameters even if `@param`
> directives are missing, and that default values are always documented.
> Furthermore, it would relieve authors from providing code samples manually.
> The general format could look like:
> {noformat}
> $object->method(
> param1 => $value1, # required
> param2 => $value2, # default: xxx
> );
> {noformat}
> The name of the invocant {{$object}} can be derived from the class name, the
> names of the values from their types. For example:
> {noformat}
> $searcher->hits(
> query => $obj, # required
> offset => $uint32, # default: 0
> num_wanted => $uint32, # default: 10
> sort_spec => $sort_spec, # default: undef
> );
> {noformat}
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
