Updates POD markup for Dataset, DataObj and its sub-classes for #188.

perl_lib/EPrints/DataObj/Access.pm

@@ -7,140 +7,149 @@
 #
 ######################################################################
 
+=pod
+
+=for Pod2Wiki
 
 =head1 NAME
 
 B<EPrints::DataObj::Access> - Accesses to the Web server
 
 =head1 DESCRIPTION
 
-Inherits from L<EPrints::DataObj>.
+Accesses to particular abstract/summary pages (views) or publication 
+documents (downloads).
 
-=head1 INSTANCE VARIABLES
+=head1 CORE METADATA FIELDS
 
 =over 4
 
-=item $obj->{ "data" }
+=item accessid (counter)
 
-=item $obj->{ "dataset" }
+Unique ID for the access.
 
-=item $obj->{ "session" }
+=item datestamp (timestamp)
 
-=back
-
-=head1 CORE FIELDS
-
-=over 4
+Time of access.
 
-=item accessid
+=item requester_id (text)
 
-Unique id for the access.
+ID of the requesting user-agent. (Typically an IP address).
 
-=item datestamp
+=item requester_user_agent (text)
 
-Time of access.
+The HTTP user agent string. (Useful for robots spotting).
 
-=item requester_id
+=item requester_country (text)
 
-Id of the requesting user-agent (typically IP address).
+The country from which the request originated. (Typically determined 
+using L<Geo::IP>). 
 
-=item requester_user_agent
+=item requester_institution (text)
 
-The HTTP user agent string (useful for robots spotting).
+The institution from which the request originated. (This could be used 
+to store the Net-Name from a WHOIS lookup).
 
-=item requester_country
+=item referring_entity_id (longtext)
 
-Country the request originated from.
+ID of the object from which the user agent came from (i.e. HTTP 
+referrer).
 
-=item requester_institution
+=item service_type_id (text)
 
-Institution the request originated from.
+Id of the type of service requested. (E.g. abstract view or full text
+download).
 
-=item referring_entity_id
+=item referent_id (int)
 
-Id of the object from which the user agent came from (i.e. HTTP referrer).
+ID of the object requested. (Normally the eprint ID).
 
-=item service_type_id
+=item referent_docid (int)
 
-Id of the type of service requested.
+ID of the document requested (if relevant).
 
-=item referent_id
+=back
 
-Id of the object requested.
+=head1 REFERENCES AND RELATED OBJECTS
 
-=item referent_docid
+None.
 
-Id of the document requested (if relevent).
+=head1 INSTANCE VARIABLES
 
-=back
+See L<EPrints::DataObj/INSTANCE_VARIABLES>.
 
 =head1 METHODS
 
-=over 4
-
 =cut
 
 package EPrints::DataObj::Access;
 
-@ISA = ( 'EPrints::DataObj::SubObject' );
+@ISA = ( 'EPrints::DataObj' );
 
 use EPrints;
 
 use strict;
 
-=item $thing = EPrints::DataObj::Access->get_system_field_info
 
-Core fields contained in a Web access.
+######################################################################
+=pod
+
+=back
+
+=head2 Class Methods
 
 =cut
+######################################################################
 
-sub get_system_field_info
-{
-	my( $class ) = @_;
+######################################################################
+=pod
 
-	return
-	( 
-		{ name=>"accessid", type=>"counter", required=>1, can_clone=>0,
-			sql_counter=>"accessid" },
+=over 4
 
-		{ name=>"datestamp", type=>"timestamp", required=>1, },
+=item $fields = EPrints::DataObj::Access->get_system_field_info
 
-		{ name=>"requester_id", type=>"text", required=>1, text_index=>0, },
+Returns an array describing the system metadata of the access dataset.
 
-		{ name=>"requester_user_agent", type=>"text", required=>0, text_index=>0, },
+=cut
+######################################################################
 
-		{ name=>"requester_country", type=>"text", required=>0, text_index=>0, },
+sub get_system_field_info
+{
+    my( $class ) = @_;
 
-		{ name=>"requester_institution", type=>"text", required=>0, text_index=>0, },
+    return
+    (
+        { name=>"accessid", type=>"counter", required=>1, can_clone=>0,
+            sql_counter=>"accessid" },
 
-		{ name=>"referring_entity_id", type=>"longtext", required=>0, text_index=>0, },
+        { name=>"datestamp", type=>"timestamp", required=>1, },
 
-		{ name=>"service_type_id", type=>"text", required=>1, text_index=>0, },
+        { name=>"requester_id", type=>"text", required=>1, text_index=>0, },
 
-		{ name=>"referent_id", type=>"int", required=>1, text_index=>0, },
+        { name=>"requester_user_agent", type=>"text", required=>0, text_index=>0, },
 
-		{ name=>"referent_docid", type=>"int", required=>0, text_index=>0, },
-	);
-}
+        { name=>"requester_country", type=>"text", required=>0, text_index=>0, },
 
-######################################################################
+        { name=>"requester_institution", type=>"text", required=>0, text_index=>0, },
 
-=back
+        { name=>"referring_entity_id", type=>"longtext", required=>0, text_index=>0, },
 
-=head2 Class Methods
+        { name=>"service_type_id", type=>"text", required=>1, text_index=>0, },
 
-=over 4
+        { name=>"referent_id", type=>"int", required=>1, text_index=>0, },
 
-=cut
+        { name=>"referent_docid", type=>"int", required=>0, text_index=>0, },
+    );
+}
 
-######################################################################
 
 ######################################################################
 =pod
 
 =item $dataset = EPrints::DataObj::Access->get_dataset_id
 
-Returns the id of the L<EPrints::DataSet> object to which this record belongs.
+Returns the ID of the L<EPrints::DataSet> object to which this record
+belongs.
 
 =cut
 ######################################################################
@@ -151,18 +160,26 @@ sub get_dataset_id
 }
 
 ######################################################################
+=pod
+
+=back
 
 =head2 Object Methods
 
 =cut
+######################################################################
 
 ######################################################################
+=pod
+
+=over 4
 
-=item $dataobj->get_referent_id()
+=item $referent_id = $access->get_referent_id
 
-Return the fully qualified referent id.
+Returns the fully-qualified referent ID.
 
 =cut
+######################################################################
 
 sub get_referent_id
 {
@@ -177,11 +194,16 @@ sub get_referent_id
 	return $id;
 }
 
-=item $dataobj->get_requester_id()
 
-Return the fully qualified requester id.
+######################################################################
+=pod
+
+=item $requester_id = $access->get_requester_id
+
+Return the fully-qualified requester ID.
 
 =cut
+######################################################################
 
 sub get_requester_id
 {
@@ -196,29 +218,27 @@ sub get_requester_id
 
 1;
 
-__END__
+######################################################################
+=pod
 
 =back
 
 =head1 SEE ALSO
 
 L<EPrints::DataObj> and L<EPrints::DataSet>.
 
-=cut
-
-
 =head1 COPYRIGHT
 
-=for COPYRIGHT BEGIN
+=begin COPYRIGHT
 
-Copyright 2021 University of Southampton.
+Copyright 2022 University of Southampton.
 EPrints 3.4 is supplied by EPrints Services.
 
 http://www.eprints.org/eprints-3.4/
 
-=for COPYRIGHT END
+=end COPYRIGHT
 
-=for LICENSE BEGIN
+=begin LICENSE
 
 This file is part of EPrints 3.4 L<http://www.eprints.org/>.
 
@@ -235,5 +255,5 @@ You should have received a copy of the GNU Lesser General Public
 License along with EPrints 3.4.
 If not, see L<http://www.gnu.org/licenses/>.
 
-=for LICENSE END
+=end LICENSE