From 02cd1e0b8c148ba2ec5f8efd133c5a8938e92c1b Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@finalrewind.org>
Date: Fri, 6 May 2011 12:05:29 +0200
Subject: Some documentation work

---
 bin/raps2        |   2 +
 lib/App/Raps2.pm | 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 114 insertions(+)

diff --git a/bin/raps2 b/bin/raps2
index b7d1bc2..5aa3d34 100755
--- a/bin/raps2
+++ b/bin/raps2
@@ -87,6 +87,8 @@ None so far.
 
 =item * File::Slurp
 
+=item * xclip (for C<< raps2 get >>)
+
 =back
 
 =head1 BUGS AND LIMITATIONS
diff --git a/lib/App/Raps2.pm b/lib/App/Raps2.pm
index 00cbde4..6710d48 100644
--- a/lib/App/Raps2.pm
+++ b/lib/App/Raps2.pm
@@ -1,6 +1,31 @@
 package App::Raps2;
 
+=head1 NAME
 
+App::Raps2 - A Password safe
+
+=head1 SYNOPSIS
+
+    use App::Raps2;
+
+    my $raps2 = App::Raps2->new();
+    my ($action, @args) = @ARGV;
+
+    $raps2->sanity_check();
+    $raps2->load_config();
+
+    given ($action) {
+        when ('add')  { $raps2->cmd_add(@args) }
+        when ('dump') { $raps2->cmd_dump(@args) }
+        when ('get')  { $raps2->cmd_get(@args) }
+        when ('info') { $raps2->cmd_info(@args) }
+    }
+
+=head1 DESCRIPTION
+
+B<App::Raps2> is the backend for B<raps2>, a simple commandline password safe.
+
+=cut
 
 
 use strict;
@@ -19,6 +44,14 @@ use File::Slurp qw(slurp write_file);
 our @EXPORT_OK = ();
 our $VERSION = '0.1';
 
+=head1 METHODS
+
+=head2 create_salt()
+
+Returns a 16-character random salt for App::Raps2::Password(3pm).
+
+=cut
+
 sub create_salt {
 	my $salt = q{};
 
@@ -29,6 +62,13 @@ sub create_salt {
 	return $salt;
 }
 
+=head2 file_to_hash($file)
+
+Reads $file (lines with key/value separated by whitespace) and returns a hash
+with its key/value pairs.
+
+=cut
+
 sub file_to_hash {
 	my ($file) = @_;
 	my %ret;
@@ -45,6 +85,22 @@ sub file_to_hash {
 	return %ret;
 }
 
+=head2 new(%conf)
+
+Returns a new B<App::Raps2> object.
+
+Accepted configuration parameters are:
+
+=over
+
+=item B<cost> => I<int>
+
+B<cost> of key setup, passed on to App::Raps2::Password(3pm).
+
+=back
+
+=cut
+
 sub new {
 	my ($obj, %conf) = @_;
 	my $ref = {};
@@ -60,6 +116,15 @@ sub new {
 	return bless($ref, $obj);
 }
 
+=head2 ->sanity_check()
+
+Create working directories (~/.config/raps2 and ~/.local/share/raps2, or the
+respective XDG environment variable contents), if they don't exist yet.
+
+Calls B<create_config> if no raps2 config was found.
+
+=cut
+
 sub sanity_check {
 	my ($self) = @_;
 
@@ -73,6 +138,12 @@ sub sanity_check {
 	return;
 }
 
+=head2 ->get_master_password()
+
+Asks the user for the master passphrase.
+
+=cut
+
 sub get_master_password {
 	my ($self) = @_;
 	my $pass = $self->ui()->read_pw('Master Password', 0);
@@ -86,6 +157,12 @@ sub get_master_password {
 	$self->{'pass'}->verify($self->{'master_hash'});
 }
 
+=head2 ->create_config()
+
+Creates a default config and asks the user to set a master password.
+
+=cut
+
 sub create_config {
 	my ($self) = @_;
 	my $cost = 12;
@@ -107,6 +184,12 @@ sub create_config {
 	);
 }
 
+=head2 ->load_config()
+
+Load config
+
+=cut
+
 sub load_config {
 	my ($self) = @_;
 	my %cfg = file_to_hash($self->{'xdg_conf'} . '/password');
@@ -115,11 +198,23 @@ sub load_config {
 	$self->{'default'}->{'cost'} //= $cfg{'cost'};
 }
 
+=head2 ->ui()
+
+Returns the App::Raps2::UI(3pm) object.
+
+=cut
+
 sub ui {
 	my ($self) = @_;
 	return $self->{'ui'};
 }
 
+=head2 ->cmd_add($name)
+
+Adds a new password file called $name.
+
+=cut
+
 sub cmd_add {
 	my ($self, $name) = @_;
 	my $pwfile = $self->{'xdg_data'} . "/${name}";
@@ -155,6 +250,12 @@ sub cmd_add {
 	);
 }
 
+=head2 ->cmd_dump($name)
+
+Dumps the content of $name.
+
+=cut
+
 sub cmd_dump {
 	my ($self, $name) = @_;
 	my $pwfile = $self->{'xdg_data'} . "/${name}";
@@ -179,6 +280,12 @@ sub cmd_dump {
 	}
 }
 
+=head2 ->cmd_get($name)
+
+Puts the password saved in $name into the X clipboard.
+
+=cut
+
 sub cmd_get {
 	my ($self, $name) = @_;
 	my $pwfile = $self->{'xdg_data'} . "/${name}";
@@ -200,6 +307,11 @@ sub cmd_get {
 	}
 }
 
+=head2 ->cmd_info($name)
+
+Prints unencrypted information about $name.
+
+=cut
 
 sub cmd_info {
 	my ($self, $name) = @_;
-- 
cgit v1.2.3