X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=lib%2FFile%2FKDBX.pm;h=fee9dc5ab854a7fce3d5376a1e9e09b1463c33de;hb=fe0093f5f317cd136a2328abb7b0c31a69d4fe33;hp=4151891f1197de86fa4a42b4a1a609bd47e93e5c;hpb=808d6cac614e8cd1ecb4f62570f49171e5169fa4;p=chaz%2Fp5-File-KDBX

diff --git a/lib/File/KDBX.pm b/lib/File/KDBX.pm
index 4151891..fee9dc5 100644
--- a/lib/File/KDBX.pm
+++ b/lib/File/KDBX.pm
@@ -1155,11 +1155,11 @@ our %PLACEHOLDERS = (
 
     $kdbx->lock;
 
-Encrypt all protected binaries strings in a database. The encrypted strings are stored in
-a L<File::KDBX::Safe> associated with the database and the actual strings will be replaced with C<undef> to
+Encrypt all protected strings and binaries in a database. The encrypted data is stored in
+a L<File::KDBX::Safe> associated with the database and the actual values will be replaced with C<undef> to
 indicate their protected state. Returns itself to allow method chaining.
 
-You can call C<code> on an already-locked database to memory-protect any unprotected strings and binaries
+You can call C<lock> on an already-locked database to memory-protect any unprotected strings and binaries
 added after the last time the database was locked.
 
 =cut
@@ -1192,8 +1192,8 @@ sub lock {
 
     $kdbx->unlock;
 
-Decrypt all protected strings in a database, replacing C<undef> placeholders with unprotected values. Returns
-itself to allow method chaining.
+Decrypt all protected strings and binaries in a database, replacing C<undef> value placeholders with their
+actual, unprotected values. Returns itself to allow method chaining.
 
 =cut
 
@@ -1216,6 +1216,14 @@ C<undef> if the database is already unlocked.
 
 See L</lock> and L</unlock>.
 
+Example:
+
+    {
+        my $guard = $kdbx->unlock_scoped;
+        ...;
+    }
+    # $kdbx is now memory-locked
+
 =cut
 
 sub unlock_scoped {
@@ -1249,13 +1257,13 @@ sub peek {
 
     $bool = $kdbx->is_locked;
 
-Get whether or not a database's strings are memory-protected. If this is true, then some or all of the
-protected strings within the database will be unavailable (literally have C<undef> values) until L</unlock> is
-called.
+Get whether or not a database's contents are in a locked (i.e. memory-protected) state. If this is true, then
+some or all of the protected strings and binaries within the database will be unavailable (literally have
+C<undef> values) until L</unlock> is called.
 
 =cut
 
-sub is_locked { $_[0]->_safe ? 1 : 0 }
+sub is_locked { !!$_[0]->_safe }
 
 ##############################################################################
 
@@ -1419,8 +1427,8 @@ sub randomize_seeds {
     $key = $kdbx->key($primitive);
 
 Get or set a L<File::KDBX::Key>. This is the master key (e.g. a password or a key file that can decrypt
-a database). You can also pass a primitive that can be cast to a B<Key>. See L<File::KDBX::Key/new> for an
-explanation of what the primitive can be.
+a database). You can also pass a primitive castable to a B<Key>. See L<File::KDBX::Key/new> for an explanation
+of what the primitive can be.
 
 You generally don't need to call this directly because you can provide the key directly to the loader or
 dumper when loading or dumping a KDBX file.
@@ -1708,7 +1716,7 @@ A text string associated with the database. Often unset.
 
 The UUID of a cipher used to encrypt the database when stored as a file.
 
-See L</File::KDBX::Cipher>.
+See L<File::KDBX::Cipher>.
 
 =attr compression_flags
 
@@ -1813,7 +1821,7 @@ Number of days until the agent should prompt to recommend changing the master ke
 Number of days until the agent should prompt to force changing the master key.
 
 Note: This is purely advisory. It is up to the individual agent software to actually enforce it.
-C<File::KDBX> does NOT enforce it.
+B<File::KDBX> does NOT enforce it.
 
 =attr custom_icons
 
@@ -2372,7 +2380,7 @@ your own query logic, like this:
 
 Iterators are the built-in way to navigate or walk the database tree. You get an iterator from L</entries>,
 L</groups> and L</objects>. You can specify the search algorithm to iterate over objects in different orders
-using the C<algorith> option, which can be one of these L<constants|File::KDBX::Constants/":iteration">:
+using the C<algorithm> option, which can be one of these L<constants|File::KDBX::Constants/":iteration">:
 
 =for :list
 * C<ITERATION_IDS> - Iterative deepening search (default)
@@ -2411,12 +2419,12 @@ B<TODO> - This is a planned feature, not yet implemented.
 =head1 ERRORS
 
 Errors in this package are constructed as L<File::KDBX::Error> objects and propagated using perl's built-in
-mechanisms. Fatal errors are propagated using L<functions/die> and non-fatal errors (a.k.a. warnings) are
-propagated using L<functions/warn> while adhering to perl's L<warnings> system. If you're already familiar
-with these mechanisms, you can skip this section.
+mechanisms. Fatal errors are propagated using L<perlfunc/"die LIST"> and non-fatal errors (a.k.a. warnings)
+are propagated using L<perlfunc/"warn LIST"> while adhering to perl's L<warnings> system. If you're already
+familiar with these mechanisms, you can skip this section.
 
-You can catch fatal errors using L<functions/eval> (or something like L<Try::Tiny>) and non-fatal errors using
-C<$SIG{__WARN__}> (see L<variables/%SIG>). Examples:
+You can catch fatal errors using L<perlfunc/"eval BLOCK"> (or something like L<Try::Tiny>) and non-fatal
+errors using C<$SIG{__WARN__}> (see L<perlvar/%SIG>). Examples:
 
     use File::KDBX::Error qw(error);