lucy-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nick Wellnhofer (JIRA)" <j...@apache.org>
Subject [lucy-issues] [jira] [Created] (CLOWNFISH-64) Autogenerate subroutine synopses in Perl POD
Date Sun, 29 Nov 2015 10:50:10 GMT
Nick Wellnhofer created CLOWNFISH-64:
----------------------------------------

             Summary: Autogenerate subroutine synopses 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 synopses 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 synopses 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)

Mime
View raw message