[
https://issues.apache.org/jira/browse/CLOWNFISH-64?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Nick Wellnhofer updated CLOWNFISH-64:
-------------------------------------
Description:
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}
was:
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}
Summary: Autogenerate subroutine code samples in Perl POD (was:
Autogenerate subroutine synopses in Perl POD)
> 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)
