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 'B' classes
Date Sat, 17 Jun 2017 23:30:14 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 338f170  RDoc comments for 'B' classes
338f170 is described below

commit 338f1703b908174d6e7f294e73ce873420255775
Author: Sam Ruby <rubys@intertwingly.net>
AuthorDate: Sat Jun 17 19:30:00 2017 -0400

    RDoc comments for 'B' classes
---
 lib/whimsy/asf/agenda.rb | 28 ++++++++++++++++++++++++++++
 lib/whimsy/asf/ldap.rb   | 39 +++++++++++++++++++++++++++++++++++----
 2 files changed, 63 insertions(+), 4 deletions(-)

diff --git a/lib/whimsy/asf/agenda.rb b/lib/whimsy/asf/agenda.rb
index 0687841..b8100c1 100644
--- a/lib/whimsy/asf/agenda.rb
+++ b/lib/whimsy/asf/agenda.rb
@@ -6,11 +6,18 @@ require 'tzinfo/data'
 require 'digest/md5'
 
 module ASF
+  #
+  # module which contains the Agenda class
+  #
   module Board
   end
 end
 
+#
+# Class which contains a number of parsers.
+#
 class ASF::Board::Agenda
+  # mapping of agenda section numbers to section names
   CONTENTS = {
     '2.' => 'Roll Call',
     '3A' => 'Minutes',
@@ -23,15 +30,23 @@ class ASF::Board::Agenda
   }
 
   @@parsers = []
+  # convenience method.  If passed a file, will create an instance of this
+  # class and call the parse method on that object.  If passed a block, will
+  # add that block to the list of parsers.
   def self.parse(file=nil, quick=false, &block)
     @@parsers << block if block
     new.parse(file, quick)  if file
   end
 
+  # start with an empty list of sections.  Sections are added and returned by
+  # calling the <tt>parse</tt> method.
   def initialize
     @sections = {}
   end
 
+  # helper method to scan a section for a pattern.  Regular expression named
+  # matches will be captured and the section will be added to <tt>@sections</tt>
+  # if a match is found.
   def scan(text, pattern, &block)
     # convert tabs to spaces
     text.gsub!(/^(\t+)/) {|tabs| ' ' * (8*tabs.length)}
@@ -53,6 +68,17 @@ class ASF::Board::Agenda
     end
   end
 
+  # parse a board agenda file by passing it through each parser.  Additionally,
+  # converts the file to utf-8, adds index markers for major sections, looks
+  # for flagged reports, and performs various minor cleanup actions.
+  #
+  # If <tt>quick</tt> is <tt>false</tt>, cross-checks with committee
membership
+  # will be performed.  This supports the board agenda tools's strategy to
+  # quickly display possibly stale and possible incomplete data and then to
+  # update the presentation using React.JS once later and/or more complete
+  # data is available.
+  #
+  # Returns a list of sections.
   def parse(file, quick=false)
     @file = file
     @quick = quick
@@ -136,10 +162,12 @@ class ASF::Board::Agenda
     @sections.values
   end
 
+  # provide a link to the collated minutes for a given report
   def minutes(title)
     "https://whimsy.apache.org/board/minutes/#{title.gsub(/\W/,'_')}"
   end
 
+  # convert a PST/PDT time to UTC as a JavaScript integer
   def timestamp(time)
     date = @file[/(\w+ \d+, \d+)/]
     tz = TZInfo::Timezone.get('America/Los_Angeles')
diff --git a/lib/whimsy/asf/ldap.rb b/lib/whimsy/asf/ldap.rb
index 46fedd8..c0140d2 100644
--- a/lib/whimsy/asf/ldap.rb
+++ b/lib/whimsy/asf/ldap.rb
@@ -363,7 +363,18 @@ module ASF
     weakref(:members) {Group.find('member').members}
   end
 
+  # Superclass for all classes which are backed by LDAP data.  Encapsulates
+  # the management of collections to weak references to instance data, for
+  # both performance and funcational reasons.  Sequentially finding the same
+  # same object will return the same instance unless the prior instance has
+  # been reclaimed by garbage collection.  This often prevents large numbers
+  # of requests to fetch the same data from LDAP.
+  #
+  # This class also contains a number of helper classes that will construct
+  # various LDAP <tt>mod</tt> objects.
   class Base
+    # Simple name for the LDAP object, generally the value of <tt>uid</tt>
+    # for people, and the value of <tt>cn</tt> for all of the rest.
     attr_reader :name
 
     # define default sort key (make Base objects sortable)
@@ -371,26 +382,36 @@ module ASF
       @name <=> other.name
     end
 
+    # return the LDAP base for this object: identifies the subtree where
+    # which this object can be found.
     def self.base
       @base
     end
 
+    # return the LDAP base for this object: identifies the subtree where
+    # which this object can be found.
     def base
       self.class.base
     end
 
+    # return the collection of instances of this class, as a hash.  Note the
+    # values are weak references, so may have already been reclaimed.
     def self.collection
       @collection ||= Hash.new
     end
 
+    # Find an instance of this class, given a name
     def self.[] name
       new(name)
     end
 
+    # Find an instance of this class, given a name
     def self.find name
       new(name)
     end
 
+    # Create an instance of this class, given a name.  Note: if an instance
+    # already exists, it will return a handle to the existing object.
     def self.new name
       begin
         object = collection[name]
@@ -401,34 +422,44 @@ module ASF
       super
     end
 
+    # create an instance of this class, returning a weak reference to the
+    # object for reuse.  Note: self.new will check for such a reference and
+    # return it in favor of allocating a new object.
     def initialize name
       self.class.collection[name] = WeakRef.new(self)
       @name = name
     end
 
+    # returns a reference to the underlying object.  Useful for converting
+    # weak references to strong references.
     def reference
       self
     end
 
+    # construct a weak reference to this object
     def weakref(attr, &block)
       ASF.dereference_weakref(self, attr, &block)
     end
 
-    unless Object.respond_to? :id
-      def id
-        @name
-      end
+    # Return the simple name for this LDAP object.  This is the value of
+    # <tt>uid</tt> for people objects, and the value of <tt>cn</tt>
for all
+    # other objects.
+    def id
+      @name
     end
 
+    # helper method to construct LDAP_MOD_ADD objects
     def self.mod_add(attr, vals)
       ::LDAP::Mod.new(::LDAP::LDAP_MOD_ADD, attr.to_s, Array(vals))
     end
 
+    # helper method to construct LDAP_MOD_REPLACE objects
     def self.mod_replace(attr, vals)
       vals = Array(vals) unless Hash === vals
       ::LDAP::Mod.new(::LDAP::LDAP_MOD_REPLACE, attr.to_s, vals)
     end
 
+    # helper method to construct LDAP_MOD_DELETE objects
     def self.mod_delete(attr, vals)
       ::LDAP::Mod.new(::LDAP::LDAP_MOD_DELETE, attr.to_s, Array(vals))
     end

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

Mime
View raw message