add POD for Node and NodeIp

Netdisco/lib/Netdisco/DB/Result/Node.pm

@@ -48,22 +48,88 @@ __PACKAGE__->set_primary_key("mac", "switch", "port");
 # Created by DBIx::Class::Schema::Loader v0.07015 @ 2012-01-07 14:20:02
 # DO NOT MODIFY THIS OR ANYTHING ABOVE! md5sum:sGGyKEfUkoIFVtmj1wnH7A
 
+=head1 RELATIONSHIPS
+
+=head2 device
+
+Returns the single C<device> to which this Node entry was associated at the
+time of discovery.
+
+The JOIN is of type LEFT, in case the C<device> is no longer present in the
+database but the relation is being used in C<search()>.
+
+=cut
+
 __PACKAGE__->belongs_to( device => 'Netdisco::DB::Result::Device',
   { 'foreign.ip' => 'self.switch' }, { join_type => 'LEFT' } );
 
+=head2 device_port
+
+Returns the single C<device_port> to which this Node entry was associated at
+the time of discovery.
+
+The JOIN is of type LEFT, in case the C<device> is no longer present in the
+database but the relation is being used in C<search()>.
+
+=cut
+
 # device port may have been deleted (reconfigured modules?) but node remains
 __PACKAGE__->belongs_to( device_port => 'Netdisco::DB::Result::DevicePort',
   { 'foreign.ip' => 'self.switch', 'foreign.port' => 'self.port' },
   { join_type => 'LEFT' }
 );
 
+=head2 ips
+
+Returns the set of C<node_ip> entries associated with this Node. That is, the
+IP addresses which this MAC address was hosting at the time of discovery.
+
+Note that the Active status of the returned IP entries will all be the same as
+the current Node's.
+
+=cut
+
 __PACKAGE__->has_many( ips => 'Netdisco::DB::Result::NodeIp',
   { 'foreign.mac' => 'self.mac', 'foreign.active' => 'self.active' } );
 
-__PACKAGE__->belongs_to( oui => 'Netdisco::DB::Result::Oui', 'oui' );
+=head2 oui
+
+Returns the C<oui> table entry matching this Node. You can then join on this
+relation and retrieve the Company name from the related table.
+
+The JOIN is of type LEFT, in case the OUI table has not been populated.
+
+=cut
+
+__PACKAGE__->belongs_to( oui => 'Netdisco::DB::Result::Oui', 'oui',
+  { join_type => 'LEFT' } );
+
+=head1 ADDITIONAL COLUMNS
+
+=head2 time_first_stamp
+
+Formatted version of the C<time_first> field, accurate to the minute.
+
+The format is somewhat like ISO 8601 or RFC3339 but without the middle C<T>
+between the date stamp and time stamp. That is:
+
+ 2012-02-06 12:49
+
+=cut
 
-# accessors for custom formatted columns
 sub time_first_stamp { return (shift)->get_column('time_first_stamp') }
+
+=head2 time_last_stamp
+
+Formatted version of the C<time_last> field, accurate to the minute.
+
+The format is somewhat like ISO 8601 or RFC3339 but without the middle C<T>
+between the date stamp and time stamp. That is:
+
+ 2012-02-06 12:49
+
+=cut
+
 sub time_last_stamp  { return (shift)->get_column('time_last_stamp')  }
 
 1;

Netdisco/lib/Netdisco/DB/Result/NodeIp.pm

@@ -37,6 +37,18 @@ __PACKAGE__->set_primary_key("mac", "ip");
 # Created by DBIx::Class::Schema::Loader v0.07015 @ 2012-01-07 14:20:02
 # DO NOT MODIFY THIS OR ANYTHING ABOVE! md5sum:9+CuvuVWH88WxAf6IBij8g
 
+=head1 GENERAL NOTES
+
+This Result Class for the C<node_ip> table supports sites that have customized
+their table to include a C<dns> column, containing a cached DNS record for the
+Node at the time of discovery.
+
+Calling the C<dns()> accessor will either return the content of that field if
+the field is configured and installed, or else perform a live DNS lookup on
+the IP field within the record (returning the first PTR, or undef).
+
+=cut
+
 # XXX uncomment the following two lines if you have a "dns" column XXX
 # XXX in your node_ip table which caches the host's name           XXX
 #__PACKAGE__->add_column("dns" =>
@@ -61,6 +73,17 @@ sub dns {
   return undef;
 }
 
+=head1 RELATIONSHIPS
+
+=head2 oui
+
+Returns the C<oui> table entry matching this Node. You can then join on this
+relation and retrieve the Company name from the related table.
+
+The JOIN is of type LEFT, in case the OUI table has not been populated.
+
+=cut
+
 __PACKAGE__->belongs_to( oui => 'Netdisco::DB::Result::Oui',
     sub {
         my $args = shift;
@@ -72,8 +95,38 @@ __PACKAGE__->belongs_to( oui => 'Netdisco::DB::Result::Oui',
     { join_type => 'LEFT' }
 );
 
+=head2 node_ips
+
+Returns the set of all C<node_ip> entries which are associated together with
+this IP. That is, all the IP addresses hosted on the same interface (MAC
+address) as the current Node IP entry.
+
+Note that the set will include the original Node IP object itself. If you wish
+to find the I<other> IPs excluding this one, see the C<ip_aliases> helper
+routine, below.
+
+Remember you can pass a filter to this method to find only active or inactive
+nodes, but do take into account that both the C<node> and C<node_ip> tables
+include independent C<active> fields.
+
+=cut
+
 __PACKAGE__->has_many( node_ips => 'Netdisco::DB::Result::NodeIp',
   { 'foreign.mac' => 'self.mac' } );
+
+=head2 nodes
+
+Returns the set of C<node> entries associated with this IP. That is, all the
+MAC addresses recorded which have ever hosted this IP Address.
+
+Remember you can pass a filter to this method to find only active or inactive
+nodes, but do take into account that both the C<node> and C<node_ip> tables
+include independent C<active> fields.
+
+See also the C<node_sightings> helper routine, below.
+
+=cut
+
 __PACKAGE__->has_many( nodes => 'Netdisco::DB::Result::Node',
   { 'foreign.mac' => 'self.mac' } );
 
@@ -86,6 +139,30 @@ my $search_attr = {
     '+as' => [qw/ time_first_stamp time_last_stamp /],
 };
 
+=head2 ip_aliases( \%cond, \%attrs? )
+
+Returns the set of other C<node_ip> entries hosted on the same interface (MAC
+address) as the current Node IP, excluding the current IP itself.
+
+Remember you can pass a filter to this method to find only active or inactive
+nodes, but do take into account that both the C<node> and C<node_ip> tables
+include independent C<active> fields.
+
+=over 4
+
+=item *
+
+Results are ordered by time last seen.
+
+=item *
+
+Additional columns C<time_first_stamp> and C<time_last_stamp> provide
+preformatted timestamps of the C<time_first> and C<time_last> fields.
+
+=back
+
+=cut
+
 sub ip_aliases {
     my ($row, $cond, $attrs) = @_;
     $cond ||= {};
@@ -100,6 +177,34 @@ sub ip_aliases {
       ->search($cond, $attrs);
 }
 
+=head2 node_sightings( \%cond, \%attrs? )
+
+Returns the set of C<node> entries associated with this IP. That is, all the
+MAC addresses recorded which have ever hosted this IP Address.
+
+Remember you can pass a filter to this method to find only active or inactive
+nodes, but do take into account that both the C<node> and C<node_ip> tables
+include independent C<active> fields.
+
+=over 4
+
+=item *
+
+Results are ordered by time last seen.
+
+=item *
+
+Additional columns C<time_first_stamp> and C<time_last_stamp> provide
+preformatted timestamps of the C<time_first> and C<time_last> fields.
+
+=item *
+
+A JOIN is performed on the Device table and the Device DNS column prefetched.
+
+=back
+
+=cut
+
 sub node_sightings {
     my ($row, $cond, $attrs) = @_;
     $cond ||= {};
@@ -114,8 +219,32 @@ sub node_sightings {
       ->search($cond, $attrs);
 }
 
-# accessors for custom formatted columns
+=head1 ADDITIONAL COLUMNS
+
+=head2 time_first_stamp
+
+Formatted version of the C<time_first> field, accurate to the minute.
+
+The format is somewhat like ISO 8601 or RFC3339 but without the middle C<T>
+between the date stamp and time stamp. That is:
+
+ 2012-02-06 12:49
+
+=cut
+
 sub time_first_stamp { return (shift)->get_column('time_first_stamp') }
+
+=head2 time_last_stamp
+
+Formatted version of the C<time_last> field, accurate to the minute.
+
+The format is somewhat like ISO 8601 or RFC3339 but without the middle C<T>
+between the date stamp and time stamp. That is:
+
+ 2012-02-06 12:49
+
+=cut
+
 sub time_last_stamp  { return (shift)->get_column('time_last_stamp')  }
 
 1;

Netdisco/lib/Netdisco/DB/ResultSet/NodeIp.pm

@@ -6,6 +6,17 @@ use warnings FATAL => 'all';
 
 # some customize their node_ip table to have a dns column which
 # is the cached record at the time of discovery
+
+=head1 has_dns_col
+
+Some sites customize their C<node_ip> table to include a C<dns> field which is
+the cached record at the time of node discovery.
+
+This method returns True if the C<node_ip> table is configured with a C<dns>
+column.
+
+=cut
+
 sub has_dns_col {
     my $set = shift;
     return $set->result_source->has_column('dns');