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

> 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
[download]

Cheers Rolf
_{(addicted to the Perl Programming Language :)

Wikisyntax for the Monastery
FootballPerl is like chess, only without the dice}

Comment on Re: More comprehensive style guide for Perl docs than perlpodstyle? Download Code

Replies are listed 'Best First'.
Re^2: More comprehensive style guide for Perl docs than perlpodstyle? by ikegami (Patriarch) on Jan 07, 2019 at 03:21 UTC
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`).	[reply] [d/l] [select]
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]

edit

project_rewards