Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change
 
PerlMonks  

More comprehensive style guide for Perl docs than perlpodstyle?

by nysus (Vicar)
on Jan 06, 2019 at 22:37 UTC ( #1228117=perlquestion: print w/replies, xml ) Need Help??

nysus has asked for the wisdom of the Perl Monks concerning the following question:

I'm in search of an authoritative or a least semi-authoritative style guide for perldocs. perlpodstyle doesn't go into much detail. 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. Anything out there like that?

$PM = "Perl Monk's";
$MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest Vicar";
$nysus = $PM . ' ' . $MCF;
Click here if you love Perl Monks

  • Comment on More comprehensive style guide for Perl docs than perlpodstyle?

Replies are listed 'Best First'.
Re: More comprehensive style guide for Perl docs than perlpodstyle?
by eyepopslikeamosquito (Bishop) on Jan 07, 2019 at 06:26 UTC

    Though Perl Best Practices has a chapter dedicated to Documentation, I doubt it has the specific details you're seeking. Still, you might find some useful general tips there and in Ten Essential Development Practices, also written by Damian Conway (e.g. see practice "3. Create Standard POD Templates for Modules and Applications").

    Further general advice on writing documentation for CPAN modules can be found in Writing Solid CPAN Modules, for example:

    • Separate user versus maintainer documentation. Tutorial and Reference; Examples and Cookbook; Maintainer; How your module is different to similar ones; Change log; Notes re portability, configuration & environment, performance, dependencies, bugs, limits, caveats, diagnostics, bug reporting.
    • Error Handling. Document all errors in the user's dialect.
    • Are there nicely commented tests covering the examples in the documentation? This acts as tutorial material for someone browsing the test suite and ensures the examples given in the documentation actually work.
    • Use Pod::Coverage to verify that your module's documentation is complete/comprehensive.

Re: More comprehensive style guide for Perl docs than perlpodstyle?
by LanX (Cardinal) on Jan 06, 2019 at 22:59 UTC
    > 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

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

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

        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

Re: More comprehensive style guide for Perl docs than perlpodstyle?
by Anonymous Monk on Jan 07, 2019 at 07:33 UTC

    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. Anything out there like that?

    i was young dumb and copied that junk style -- dont do that its for dummies

    just make lists

    =item c<<< $mech->get( $uri ) >>> =item c<<< $mech->get( $uri, \%form ) >>> =item c<<< $mech->get( $uri, \@form ) >>>

      Yes, I dislike non-named optional arguments to functions ... especially when there's more than one! Much prefer to handle optional arguments via a single hashref argument because I feel this scales better over time - to support a new optional argument simply support a new key value in the hash with a sensible default and old code keeps on working without modification.

      This is especially important in functions taking more than three parameters because humans are better at remembering names than orderings - as indicated by the Perl Best Practices guideline "Use a hash of named arguments for any subroutine that has more than three parameters". BTW, as indicated at Named Subroutine Parameters: Compile-time errors vs. Run-time warnings, the "reason" given for a hash reference (rather than a hash) was an error in the book: anonymous hash population is done at run-time, not compile-time; that said, Conway still stands by this advice because "Error messages that point users to the right place are definitely worth the (tiny) overhead of passing named args in a hash".

      An example of a Perl internal function with a poor interface is split, which has two (update:three) optional arguments and much surprising magic such as ' ' vs / / vs // vs /^/ as the first argument; empty leading fields preserved, empty trailing fields stripped by default; negative LIMITs; and many more. I feel split would have been much clearer and more manageable over time, if instead of using optional arguments (and special magic values for parameters) it had used a single named hashref argument to specify tricky behaviour.

        An example of a Perl internal function with a poor interface is split, which has two optional arguments ...

        Agreed. There is another function with two optional arguments which annoys me more, however, and that is substr. Even though I've read the documentation thousands of times I never quite believe that LENGTH is the optional argument and OFFSET is mandatory. Every time I go to use substr and know that it's "the wrong way round" it is just so illogical to me that I still have to pause and consult the docs again just to make sure.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://1228117]
Approved by LanX
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (9)
As of 2020-07-13 09:12 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?