in reply to Re: More comprehensive style guide for Perl docs than perlpodstyle?
in thread More comprehensive style guide for Perl docs than perlpodstyle?

Careful though. In the Perl docs, EXPR means an expression evaluated in scalar context, so you shouldn't be using EXPR in your own documentation (unless you use prototypes to ensure this). Might I recommend using meaningful variable names instead? A sample from WWW::Kickstarter: 

=head2 project_rewards

   my @rewards = $ks->project_rewards($project_id);
   my @rewards = $ks->project_rewards($project_slug);

Fetches and returns the rewards of the specified project as L<WWW::Kic
+kstarter::Data::Reward> objects.

The argument may be the project's numerical id (as returned by L<C<< $
+project->id >>|WWW::Kickstarter::Data::Project/id>) or
its "slug" (as returned by L<C<< $project->slug >>|WWW::Kickstarter::D
+ata::Project/slug>).

[download]

project_rewards

my @rewards = $ks->project_rewards($project_id);
my @rewards = $ks->project_rewards($project_slug);

[download]

Fetches and returns the rewards of the specified project as WWW::Kickstarter::Data::Reward objects.

The argument may be the project's numerical id (as returned by $project->id) or its "slug" (as returned by $project->slug).

Replies are listed 'Best First'.
Re^3: More comprehensive style guide for Perl docs than perlpodstyle?
by LanX (Saint) on Jan 07, 2019 at 14:24 UTC
    I was referring to the question

    >  to indicate that an argument to a method is optional

    not to the typing of single arguments.

    I also prefer lists with meaningful variable names with sigils.

    This makes it easier for users to simply copy and adapt it.

    Though probably

    fetch_clients( $names_aref )

    Is better written as

    fetch_clients( \@names )

    Cheers Rolf
    (addicted to the Perl Programming Language :)
    Wikisyntax for the Monastery FootballPerl is like chess, only without the dice

[reply]
[d/l]
[select]

In Section Seekers of Perl Wisdom