[lucy-issues] [jira] [Commented] (CLOWNFISH-64) Autogenerate subroutine code samples in Perl POD

["ASF GitHub Bot (JIRA)" <ji...@apache.org>]

    [ 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 <we...@aevum.de>
Date:   2015-12-12T14:34:03Z

    Autogenerate Perl subroutine code samples
    
    Resolves CLOWNFISH-64.

commit e2626d979b25c9a8f4bb8af9d48f104cdae99aeb
Author: Nick Wellnhofer <we...@aevum.de>
Date:   2015-12-12T14:37:40Z

    Remove argument summary from =head2 in POD

commit 18007a3a085fe51ebc12cd6b991770a0d6a17974
Author: Nick Wellnhofer <we...@aevum.de>
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)