whimsical-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ru...@apache.org
Subject [whimsy] branch master updated: RDoc comments for 'I' and 'L'.
Date Sun, 18 Jun 2017 16:34:40 GMT
This is an automated email from the ASF dual-hosted git repository.

rubys pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/whimsy.git


The following commit(s) were added to refs/heads/master by this push:
     new 72a0709  RDoc comments for 'I' and 'L'.
72a0709 is described below

commit 72a07092ef89ba9eb2dd85bc8bd9a06ca41cadf1
Author: Sam Ruby <rubys@intertwingly.net>
AuthorDate: Sun Jun 18 12:34:10 2017 -0400

    RDoc comments for 'I' and 'L'.
---
 lib/whimsy/asf/icla.rb | 33 ++++++++++++++++++++++++++++-----
 lib/whimsy/asf/ldap.rb | 31 +++++++++++++++++++------------
 2 files changed, 47 insertions(+), 17 deletions(-)

diff --git a/lib/whimsy/asf/icla.rb b/lib/whimsy/asf/icla.rb
index cdd3c1c..0ea6ebc 100644
--- a/lib/whimsy/asf/icla.rb
+++ b/lib/whimsy/asf/icla.rb
@@ -2,18 +2,39 @@ require 'json'
 
 module ASF
 
+  #
+  # Provide access to the contents of iclas.txt.
+  #
+  # N.B. only id and name should be considered public
+  # form and claRef may contain details of the legal name beyond that in the public name
   class ICLA
-    # N.B. only id and name should be considered public
-    # form and claRef may contain details of the legal name beyond that in the public name
-    attr_accessor :id, :legal_name, :name, :email, :form
-    attr_accessor :claRef # cla name or SVN revision info
+    # availid of the ICLA, or <tt>notinavail</tt> if no id has been issued
+    attr_accessor :id
+
+    # legal name for the individual; should not be shared
+    attr_accessor :legal_name
+
+    # public name for the individual; should match LDAP
+    attr_accessor :name
+
+    # email address from the ICLA
+    attr_accessor :email
+
+    # lists the name of the form on file; includes claRef information
+    attr_accessor :form
+
+    # cla name or SVN revision info; extracted from the form
+    attr_accessor :claRef 
 
     @@mtime = nil
 
     # list of availids that should not be used
     @@availids_reserved = nil
 
+    # location of a working copy of the officers directory in SVN
     OFFICERS = ASF::SVN.find('private/foundation/officers')
+
+    # location of the iclas.txt file; may be <tt>nil</tt> if not found.
     SOURCE = OFFICERS ? "#{OFFICERS}/iclas.txt" : nil
 
     # flush caches if source file changed
@@ -29,6 +50,7 @@ module ASF
       end
     end
 
+    # Date and time of the last change in <tt>iclas.txt</tt> in the working copy
     def self.svn_change
       self.refresh
       if SOURCE
@@ -141,7 +163,7 @@ module ASF
       "#{name}:#{rest}"
     end
 
-    # sort an entire iclas.txt file
+    # sort an entire <tt>iclas.txt</tt> file
     def self.sort(source)
       headers = source.scan(/^#.*/)
       lines = source.scan(/^\w.*/)
@@ -150,6 +172,7 @@ module ASF
         lines.sort_by {|line| lname(line + "\n")}.join("\n") + "\n"
     end
 
+    # list of reserved availids
     def self.availids_reserved
       return @@availids_reserved if @@availids_reserved
       archive = ASF::SVN['private/foundation/officers']
diff --git a/lib/whimsy/asf/ldap.rb b/lib/whimsy/asf/ldap.rb
index 4e8f1f0..243811f 100644
--- a/lib/whimsy/asf/ldap.rb
+++ b/lib/whimsy/asf/ldap.rb
@@ -37,8 +37,10 @@ require 'thread'
 
 module ASF
   module LDAP
-     # https://www.pingmybox.com/dashboard?location=304
-     # https://github.com/apache/infrastructure-puppet/blob/deployment/data/common.yaml (ldapserver::slapd_peers)
+
+     # Derived from the following sources:
+     # * https://www.pingmybox.com/dashboard?location=304
+     # * https://github.com/apache/infrastructure-puppet/blob/deployment/data/common.yaml
(ldapserver::slapd_peers)
      # Updated 2017-01-02 
     HOSTS = %w(
       ldaps://themis.apache.org:636
@@ -48,7 +50,10 @@ module ASF
       ldaps://snappy5.apache.org:636
     )
 
+    # Mutex preventing simultaneous connections to LDAP from a single process
     CONNECT_LOCK = Mutex.new
+
+    # Round robin list of LDAP hosts to be tried after failure
     HOST_QUEUE = Queue.new
 
     # fetch configuration from apache/infrastructure-puppet
@@ -110,6 +115,8 @@ module ASF
       return nil
     end
 
+    # connect to LDAP with a user and password; generally required for
+    # update operations.
     def self.bind(user, password, &block)
       dn = ASF::Person.new(user).dn
       raise ::LDAP::ResultError.new('Unknown user') unless dn
@@ -228,7 +235,7 @@ module ASF
       File.write(ldap_conf, content) unless content == File.read(ldap_conf)
     end
 
-    # dump more information on LDAP errors - modify
+    # modify an entry in LDAP; dump information on LDAP errors
     def self.modify(dn, list)
       ASF.ldap.modify(dn, list)
     rescue ::LDAP::ResultError
@@ -237,7 +244,7 @@ module ASF
       raise
     end
 
-    # dump more information on LDAP errors - add
+    # add an entry to LDAP; dump information on LDAP errors
     def self.add(dn, list)
       ASF.ldap.add(dn, list)
     rescue ::LDAP::ResultError
@@ -246,7 +253,7 @@ module ASF
       raise
     end
 
-    # dump more information on LDAP errors - delete
+    # delete an entry from LDAP; dump information on LDAP errors
     def self.delete(dn)
       ASF.ldap.delete(dn)
     rescue ::LDAP::ResultError
@@ -465,17 +472,17 @@ module ASF
     end
   end
 
+  # a hash of attributes which is not populated until the first attempt
+  # to reference a value
   class LazyHash < Hash
+    # capture an initializer to be called only if necessary.
     def initialize(&initializer)
       @initializer = initializer
     end
 
-    def load
-     return unless @initializer
-     merge! @initializer.call || {}
-     @initializer = super
-    end
-
+    # if referencing a key that is not in the hash, and the initializer has
+    # not yet been called, call the initializer, merge the results, and
+    # try again.
     def [](key)
       result = super
       if not result and not keys.include? key and @initializer
@@ -1124,7 +1131,7 @@ end
 if __FILE__ == $0
   module ASF
     module LDAP
-      def self.getHOSTS
+      def self.getHOSTS # :nodoc:
         HOSTS
       end
     end

-- 
To stop receiving notification emails like this one, please contact
['"commits@whimsical.apache.org" <commits@whimsical.apache.org>'].

Mime
View raw message