|
Re: More comprehensive style guide for Perl docs than perlpodstyle?
by eyepopslikeamosquito (Archbishop) 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.
| [reply] |
Re: More comprehensive style guide for Perl docs than perlpodstyle?
by LanX (Saint) 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
| [reply]
[d/l] |
|
|
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).
| [reply]
[d/l]
[select] |
|
|
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 )
| [reply]
[d/l]
[select] |
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 ) >>>
| [reply]
[d/l] |
|
|
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.
| [reply]
[d/l]
[select] |
|
|
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.
| [reply] |
|
|
|
|
|
|
|
|
|
|
|
