perldoc for 2fDevices lib

lemonldap-ng-portal/lib/Lemonldap/NG/Portal/Lib/2fDevices.pm

@@ -1,5 +1,25 @@
 package Lemonldap::NG::Portal::Lib::2fDevices;
 
+=pod
+
+=head1 NAME
+
+Lemonldap::NG::Portal::Lib::2fDevices - Role for registrable second factors
+
+=head1 DESCRIPTION
+
+This role provides LemonLDAP::NG modules with a high-level interface to storing
+information on registrable second factors into the persistent session.
+
+It is recommended that _2fDevices is never accessed directly from code outside
+of this module
+
+=head1 METHODS
+
+=over
+
+=cut
+
 use strict;
 use Mouse::Role;
 use JSON;
@@ -8,6 +28,30 @@ requires qw(p conf logger);
 
 our $VERSION = '2.0.15';
 
+=item update2fDevice
+
+Updates one field of a registered device
+
+    $self->update2fDevice($req, $info, $type, $key, $value, $update_key, $update_value);
+
+=over 4
+
+=item req: Current LemonLDAP::NG request
+
+=item info: hashref of current session information
+
+=item type: 'type' field of the device to update
+
+=item key, value: update the device whose 'key' field equals value
+
+=item update_key, update_value: set the matched devices' 'update_key' field to update_value
+
+=back
+
+Returns true iff the update was sucessful
+
+=cut
+
 sub update2fDevice {
     my ( $self, $req, $info, $type, $key, $value, $update_key, $update_value )
       = @_;
@@ -32,6 +76,27 @@ sub update2fDevice {
     return 0;
 }
 
+=item add2fDevice
+
+Register a new device
+
+    $self->add2fDevice($req, $info, $device);
+
+=over 4
+
+=item req: Current LemonLDAP::NG request
+
+=item info: hashref of current session information
+
+=item device: hashref of device details. It must contain at least a 'type',
+'name' and 'epoch' key
+
+=back
+
+Returns true iff the update was sucessful
+
+=cut
+
 sub add2fDevice {
     my ( $self, $req, $info, $device ) = @_;
 
@@ -46,8 +111,28 @@ sub add2fDevice {
     return 1;
 }
 
-# $devices must be a arrayref of type+epoch hashrefs:
-# [ { type => xxx, epoch => xxx }, { type => xxx, epoch => xxx } ]
+=item del2fDevices
+
+Delete the devices specified in the @$devices array
+
+    $self->del2fDevices($req, $info, $devices);
+
+=over 4
+
+=item req: Current LemonLDAP::NG request
+
+=item info: hashref of current session information
+
+=item device: arrayref of type+epoch hashrefs
+
+    [ { type => xxx, epoch => xxx }, { type => xxx, epoch => xxx } ]
+
+=back
+
+Returns true iff the update was sucessful
+
+=cut
+
 sub del2fDevices {
     my ( $self, $req, $info, $devices ) = @_;
 
@@ -83,6 +168,28 @@ sub del2fDevices {
     return 1;
 }
 
+=item del2fDevice
+
+Delete a single device
+
+    $self->del2fDevice($req, $info, $type, $epoch);
+
+=over 4
+
+=item req: Current LemonLDAP::NG request
+
+=item info: hashref of current session information
+
+=item type: type of the device to remove
+
+=item epoch: timestamp of the device to remove
+
+=back
+
+Returns true iff the update was sucessful
+
+=cut
+
 sub del2fDevice {
     my ( $self, $req, $info, $type, $epoch ) = @_;
 
@@ -90,6 +197,28 @@ sub del2fDevice {
         [ { type => $type, epoch => $epoch } ] );
 }
 
+=item find2fDevicesByKey
+
+Find devices from one of its attributes
+
+    $self->find2fDevicesByKey($req, $info, $type, $key, $value);
+
+=over 4
+
+=item req: Current LemonLDAP::NG request
+
+=item info: hashref of current session information
+
+=item type: device type
+
+=item key, value: attribute to search in the device hash and the value to filter on
+
+=back
+
+Returns an array of devices for which type, key and value match the supplied ones
+
+=cut
+
 sub find2fDevicesByKey {
     my ( $self, $req, $info, $type, $key, $value ) = @_;
 
@@ -101,11 +230,23 @@ sub find2fDevicesByKey {
     return @found;
 }
 
-## @method get2fDevices($req, $info)
-# Validate logout request
-# @param req Request object
-# @param info HashRef of session data
-# @return undef or ArrayRef of second factors
+=item get2fDevices
+
+Return all registrable devices.
+
+    $self->get2fDevices($req, $info);
+
+=over 4
+
+=item req: Current LemonLDAP::NG request
+
+=item info: hashref of current session information
+
+=back
+
+Returns an arrayref of all registrable devices, or undef if an error occured
+
+=cut
 
 sub get2fDevices {
     my ( $self, $req, $info ) = @_;
@@ -131,6 +272,27 @@ sub get2fDevices {
     }
 }
 
+=item find2fDevicesByType
+
+Return all registrable devices of a certain type. If type is not given, return
+all registrable devices
+
+    $self->find2fDevicesByType($req, $info, $type);
+
+=over 4
+
+=item req: Current LemonLDAP::NG request
+
+=item info: hashref of current session information
+
+=item type: type of registrable device to return
+
+=back
+
+Returns an array of all matching devices
+
+=cut
+
 sub find2fDevicesByType {
     my ( $self, $req, $info, $type ) = @_;
 
@@ -142,3 +304,6 @@ sub find2fDevicesByType {
     return @found;
 }
 1;
+
+=back
+