Re: More comprehensive style guide for Perl docs than perlpodstyle?

[LanX]

> For example, it doesn't mention the common practice for indicating that square brackets are used to indicate that an argument to a method is optional. 

Because AFAIK there is no such standard.

Many authors copied this convention from Unix man pages, and I find it very confusing that it looks like an anonymous array.

IMHO we are in need of a clean Perl notation.

edit

Perldoc's own convention is to list all possible combinations, like

split /PATTERN/,EXPR,LIMIT
split /PATTERN/,EXPR
split /PATTERN/
split

[ikegami]

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>).

---

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 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).

[LanX]

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 )