XOrg: POD the InputDevice module

1 files changed, 113 insertions, 17 deletions

diff --git a/XOrg/InputDevice.pm b/XOrg/InputDevice.pm
index 1c17607..9f872f9 100755
--- a/XOrg/InputDevice.pm
+++ b/XOrg/InputDevice.pm
@@ -19,7 +19,17 @@
 # Authors: Peter Hutterer <peter.hutterer@redhat.com>
 
 
-# Generic input device class
+=head1 NAME
+
+XOrg::InputDevice - Representation of an X.Org X Server input device
+
+=head1 DESCRIPTION
+
+An XOrg::InputDevice is a device created by the Xorg.log parser or the
+xinput parser. Depending on the backend used to create this device, not all
+fields are accessible.
+
+=cut
 
 package XOrg::InputDevice;
 
@@ -27,6 +37,25 @@ use warnings;
 use strict;
 
 # Class methods
+=head2 B<XOrg::InputDevice-E<gt>TYPE_MASTER_POINTER>
+
+Input device type for Master Pointer devices. Set by the xinput parser.
+
+=head2 B<XOrg::InputDevice-E<gt>TYPE_MASTER_KEYBOARD>
+
+Input device type for Master Keyboard devices. Set by the xinput parser.
+
+=head2 B<XOrg::InputDevice-E<gt>TYPE_SLAVE>
+
+Input device type for slave devices. Set by the xinput parser.
+
+=head2 B<XOrg::InputDevice-E<gt>TYPE_FLOATING_SLAVE>
+
+Input device type for floating (not attached) slave devices. Set by the
+xinput parser.
+
+=cut
+
 sub TYPE_MASTER_POINTER { return 1; }
 sub TYPE_MASTER_KEYBOARD { return 2; }
 sub TYPE_SLAVE { return 3; }
@@ -45,6 +74,11 @@ sub new {
 	return $self;
 }
 
+=head2 B<$device-E<gt>name([$name])>
+
+Returns the input device name as string.
+
+=cut
 sub name {
 	my $self = shift;
 	my $name = shift;
@@ -52,6 +86,13 @@ sub name {
 	return $self->{name};
 }
 
+=head2 B<$device-E<gt>id([$id])>
+
+Returns the unique numerical input device ID.
+
+Set by the xinput parser only.
+
+=cut
 sub id {
 	my $self = shift;
 	my $id = shift;
@@ -59,6 +100,13 @@ sub id {
 	return $self->{id};
 }
 
+=head2 B<$device-E<gt>attachment([$parent_device])>
+
+Returns the XOrg::InputDevice that is this slave device's master.
+
+Set by the xinput parser only.
+
+=cut
 sub attachment {
 	my $self = shift;
 	my $attachment = shift;
@@ -66,7 +114,13 @@ sub attachment {
 	return $self->{attachment};
 }
 
-# Input driver module
+=head2 B<$device-E<gt>module([$module])>
+
+Returns the XOrg::Module that is the driver for this input device.
+
+Set by the Xorg.log parser only.
+
+=cut
 sub module {
 	my $self = shift;
 	my $module = shift;
@@ -74,7 +128,15 @@ sub module {
 	return $self->{module};
 }
 
-# Source is "hal", "udev", "implicit", "internal" or "xorg.conf"
+
+=head2 B<$device-E<gt>source([$source])>
+
+Returns the source for this input device (e.g. C<udev>). See XOrg::XServer
+for possible sources.
+
+Set by the Xorg.log parser only.
+
+=cut
 sub source {
 	my $self = shift;
 	my $source = shift;
@@ -82,7 +144,13 @@ sub source {
 	return $self->{source};
 }
 
-# /dev/input/... device node
+=head2 B<$device-E<gt>devicenode([$path])>
+
+Returns the devicenode for this input device.
+
+Set by the Xorg.log parser only.
+
+=cut
 sub devicenode {
 	my $self = shift;
 	my $devicenode = shift;
@@ -90,11 +158,13 @@ sub devicenode {
 	return $self->{devicenode};
 }
 
-# The list of input classes that apply to this device.
-# Arguments:
-# - ref to list of input classes
-# Returns:
-# - The list of input classes
+=head2 B<$device-E<gt>inputclasses([\@classes])>
+
+Returns a list of the input classes that apply to this device.
+
+Set by the Xorg.log parser only.
+
+=cut
 sub inputclasses {
 	my $self = shift;
 	my $inputclasses = shift;
@@ -104,13 +174,29 @@ sub inputclasses {
 	return @{$self->{inputclasses}};
 }
 
+=head2 B<$device-E<gt>add_inputclass($class)>
+
+Add one more input class to the list.
+
+=cut
 sub add_inputclass {
 	my $self = shift;
 	my $cls = shift;
 	push @{$self->{inputclasses}}, $cls;
 }
 
-# Returns 1 if the device is present, or 0 if it failed to initialize.
+=head2 B<$device-E<gt>present([$bool])>
+
+Returns 1 if the device is present, or 0 if it failed to initialize.
+
+Since input devices may have multiple device nodes, it is virtually
+guaranteed that some devices may be present that are not usable
+input devices in the server. Any user of this module should check the
+present state whether this device is actually there or failed to initialize.
+
+Set by the Xorg.log parser only.
+
+=cut
 sub present {
 	my $self = shift;
 	my $present = shift;
@@ -118,18 +204,28 @@ sub present {
 	return $self->{present};
 }
 
-# The hash of options the device reported to the log.
-# Returns:
-# - A hash of the options
+=head2 B<$device-E<gt>options>
+
+The hash of {"Option Name" => "Option Value"} the device reported to the log.
+
+Set by the Xorg.log parser only. Not all options parsed by a driver may show
+up in the log, and some options may be changed after showing to the log
+(e.g. clipped into defaults). This list is an approximation only of the
+actual values in the driver.
+
+=cut
 sub options {
 	my $self = shift;
 	return %{$self->{options}};
 }
 
-# Add one option to the device
-# Arguments:
-# - option key
-# - option value
+=head2 B<$device-E<gt>add_option($name, $value)>
+
+Add one more otion to the list.
+
+Set by the Xorg.log parser only.
+
+=cut
 sub add_option {
 	my $self = shift;
 	my $opt = shift;