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 'C' classes
Date Sun, 18 Jun 2017 12:39:03 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 297ee5a  RDoc comments for 'C' classes
297ee5a is described below

commit 297ee5a74a4f99a3f8d519130319d25a6eb3a823
Author: Sam Ruby <rubys@intertwingly.net>
AuthorDate: Sun Jun 18 08:38:48 2017 -0400

    RDoc comments for 'C' classes
---
 lib/whimsy/asf/committee.rb | 81 ++++++++++++++++++++++++++++++++++++++++++---
 lib/whimsy/asf/config.rb    |  9 +++++
 lib/whimsy/asf/ldap.rb      | 38 +++++++++++++++------
 lib/whimsy/asf/mail.rb      |  5 +++
 lib/whimsy/asf/site.rb      |  2 ++
 5 files changed, 119 insertions(+), 16 deletions(-)

diff --git a/lib/whimsy/asf/committee.rb b/lib/whimsy/asf/committee.rb
index 137d14e..0348200 100644
--- a/lib/whimsy/asf/committee.rb
+++ b/lib/whimsy/asf/committee.rb
@@ -2,12 +2,54 @@ require 'time'
 
 module ASF
 
-  class Base
+  # Define super class to prevent circular references.  This class is
+  # actually defined in ldap.rb which is require'd after committee.rb.
+  class Base # :nodoc:
   end
 
+  #
+  # Representation for a committee (either a PMC, a board committee, or
+  # a President's committee).  This data is parsed from 
+  # <tt>committee-info.txt</tt>, and is augmened by data from LDAP,
+  # ASF::Site, and ASF::Mail.
+  #
+  # Note that the simple attributes which are sourced from
+  # <tt>committee-info.txt</tt> data is generally not available until
+  # ASF::Committee.load_committee_info is called.
+  #
+  # Similarly, the simple attributes which are sourced from LDAP is
+  # generally not available until ASF::Committee.preload is called.
+
   class Committee < Base
-    attr_accessor :info, :report, :roster, :established, :chairs,
-      :schedule
+    # list of chairs for this committee.  Returned as a list of hashes
+    # containing the <tt>:name</tt> and <tt>:id</tt>.  Data is obtained
from
+    # <tt>committee-info.txt</tt>.
+    attr_accessor :chairs
+
+    # list of members for this committee.  Returned as a list of ids.
+    # Data is obtained from <tt>committee-info.txt</tt>.
+    attr_reader :info
+
+    # when this committee is next expected to report.  May be a string
+    # containing values such as "Next month: missing in May", "Next month: new,
+    # montly through July".  Data is obtained from <tt>committee-info.txt</tt>.
+    attr_writer :report
+
+    # list of members for this committee.  Returned as a list of hash
+    # mapping ids to a hash of <tt>:name</tt> and <tt>:date</tt>
values. 
+    # Data is obtained from <tt>committee-info.txt</tt>.
+    attr_accessor :roster
+
+    # Date this committee was established in the format MM/YYYY.
+    # Data is obtained from <tt>committee-info.txt</tt>.
+    attr_accessor :established
+
+    # list of months when his committee typically  reports.  Returned
+    # as a comma separated string.  Data is obtained from
+    # <tt>committee-info.txt</tt>.
+    attr_accessor :schedule
+
+    # create an empty committee instance
     def initialize(*args)
       @info = []
       @chairs = []
@@ -43,6 +85,9 @@ module ASF
       cname
     end
 
+    # load committee info from <tt>committee-info.txt</tt>.  Will not reparse
+    # if the file has already been parsed and the underlying file has not
+    # changed.
     def self.load_committee_info
       board = ASF::SVN['private/committers/board']
       file = "#{board}/committee-info.txt"
@@ -52,7 +97,6 @@ module ASF
         return @committee_info 
       end
 
-
       @committee_mtime = File.mtime(file)
       @@svn_change = Time.parse(
         `svn info #{file}`[/Last Changed Date: (.*) \(/, 1]).gmtime
@@ -60,7 +104,7 @@ module ASF
       parse_committee_info File.read(file)
     end
 
-    # insert (replacing if necessary) a new committee
+    # insert (replacing if necessary) a new committee into committee-info.txt
     def self.establish(contents, pmc, date, people)
       # split into foot, sections (array) and head
       foot = contents[/^=+\s*\Z/]
@@ -88,6 +132,10 @@ module ASF
       head + '* ' + sections.join('* ') + foot
     end
 
+    # extract chairs, list of nonpmcs, roster, start date, and reporting
+    # information from <tt>committee-info.txt</tt>.  Note: this method is
+    # intended to be internal, use ASF::Committee.load_committee_info as it
+    # will cache this data.
     def self.parse_committee_info(contents)
       list = Hash.new {|hash, name| hash[name] = find(name)}
 
@@ -157,20 +205,29 @@ module ASF
       @committee_info = list.values.uniq
     end
 
+    # return a list of non-PMC committees.  Data is obtained from
+    # <tt>committee-info.txt</tt>
     def self.nonpmcs
       @nonpmcs
     end
 
+    # Finds a committee based on the name of the Committee.  Is aware of
+    # a number of aliases for a given committee.  Will set display name
+    # if the name being searched on contains an uppercase character.
     def self.find(name)
       result = super(@@namemap.call(name))
       result.display_name = name if name =~ /[A-Z]/
       result
     end
 
+    # Return the Last Changed Date for <tt>committee-info.txt</tt> in svn as
+    # a <tt>Time</tt> object.  Data is based on the previous call to
+    # ASF::Committee.load_committee_info.
     def self.svn_change
       @@svn_change
     end
 
+    # returns the (first) chair as an instance of the ASF::Person class.
     def chair
       Committee.load_committee_info
       if @chairs.length >= 1
@@ -180,28 +237,42 @@ module ASF
       end
     end
 
+    # Version of name suitable for display purposes.  Typically in uppercase.
+    # Data is sourced from <tt>committee-info.txt</tt>.
     def display_name
       Committee.load_committee_info
       @display_name || name
     end
 
+    # setter for display_name, should only be used by
+    # ASF::Committee.load_committee_info
     def display_name=(name)
       @display_name ||= name
     end
 
+    # when this committee is next expected to report.  May be a string
+    # containing values such as "Next month: missing in May", "Next month: new,
+    # montly through July".  Or may be a list of months, separated by commas.
+    # Data is obtained from <tt>committee-info.txt</tt>.
     def report
       @report || @schedule
     end
 
+    # setter for display_name, should only be used by
+    # ASF::Committee.load_committee_info
     def info=(list)
       @info = list
     end
 
+    # hash of availid => public_name for members (owners) of this committee
+    # Data is obtained from <tt>committee-info.txt</tt>.
     def names
       Committee.load_committee_info
       Hash[@roster.map {|id, info| [id, info[:name]]}]
     end
 
+    # if true, this committee is not a PMC.  
+    # Data is obtained from <tt>committee-info.txt</tt>.
     def nonpmc?
       Committee.nonpmcs.include? self
     end
diff --git a/lib/whimsy/asf/config.rb b/lib/whimsy/asf/config.rb
index be2744a..ebf0080 100644
--- a/lib/whimsy/asf/config.rb
+++ b/lib/whimsy/asf/config.rb
@@ -5,6 +5,12 @@ require 'etc'
 
 module ASF
 
+  #
+  # Support for local (development) configuration overrides to be stored in
+  # <tt>~/.whimsy</tt> files in YAML format.  Allows the specification of where
+  # subversion, git, and other files are stored, where updated files are
+  # cached, mailing list configuration, and other values.
+  #
   class Config
     @home = ENV['HOME'] || Dir.home(Etc.getpwuid.name)
 
@@ -13,6 +19,7 @@ module ASF
     # default :svn and :git
     @config[:svn] ||= '/srv/svn/*'
     @config[:git] ||= '/srv/git/*'
+
     # The cache is used for local copies of SVN files that may be updated by Whimsy
     # for example: podlings.xml
     # www/roster/views/actions/ppmc.json.rb (write)
@@ -39,6 +46,8 @@ module ASF
       $LOAD_PATH.unshift lib.untaint unless $LOAD_PATH.include? lib
     end
 
+    # Look up a configuration value by name (generally a symbol, like
+    # <tt>:svn</tt>).
     def self.get(value)
       @config[value]
     end
diff --git a/lib/whimsy/asf/ldap.rb b/lib/whimsy/asf/ldap.rb
index c0140d2..11f7550 100644
--- a/lib/whimsy/asf/ldap.rb
+++ b/lib/whimsy/asf/ldap.rb
@@ -494,7 +494,7 @@ module ASF
       ASF.search_one(base, filter, 'uid').flatten.map {|uid| find(uid)}
     end
 
-    # pre-fetch a given attribute, for a given list of people
+    # pre-fetch a given set of attributes, for a given list of people
     def self.preload(attributes, people={})
       list = Hash.new {|hash, name| hash[name] = find(name)}
 
@@ -866,10 +866,13 @@ module ASF
   class Committee < Base
     @base = 'ou=pmc,ou=committees,ou=groups,dc=apache,dc=org'
 
+    # return a list of committees, from LDAP.
     def self.list(filter='cn=*')
       ASF.search_one(base, filter, 'cn').flatten.map {|cn| Committee.find(cn)}
     end
 
+    # fetch <tt>dn</tt>, <tt>member</tt>, <tt>modifyTimestamp</tt>,
and
+    # <tt>createTimestamp</tt> for all committees in LDAP.
     def self.preload
       Hash[ASF.search_one(base, "cn=*", %w(dn member modifyTimestamp createTimestamp)).map
do |results|
         cn = results['dn'].first[/^cn=(.*?),/, 1]
@@ -882,7 +885,11 @@ module ASF
       end]
     end
 
-    attr_accessor :modifyTimestamp, :createTimestamp
+    # Date this committee was last modified in LDAP.
+    attr_accessor :modifyTimestamp
+
+    # Date this committee was initially created in LDAP.
+    attr_accessor :createTimestamp
 
     # return committee only if it actually exits
     def self.[] name
@@ -890,10 +897,14 @@ module ASF
       committee.members.empty? ? nil : committee
     end
 
+    # setter for members attribute, should only be used by 
+    # ASF::Committee.preload
     def members=(members)
       @members = WeakRef.new(members)
     end
 
+    # DEPRECATED.  List of members for this committee.  Use owners as it
+    # is less ambiguous.
     def members
       members = weakref(:members) do
         ASF.search_one(base, "cn=#{name}", 'member').flatten
@@ -902,7 +913,8 @@ module ASF
       members.map {|uid| Person.find uid[/uid=(.*?),/,1]}
     end
 
-    # transitional methods
+    # List of owners for this committee, i.e. people who are members of the
+    # committee and have update access.  Data is obtained from LDAP.
     def owners
       if name == 'incubator'
         ASF::Project.find('incubator').owners
@@ -911,6 +923,8 @@ module ASF
       end
     end
 
+    # List of committers for this committee.  Data is obtained from LDAP.  This
+    # data is generally stored in an attribute named <tt>member</tt>.
     def committers
       if name == 'incubator'
         ASF::Project.find('incubator').members
@@ -919,7 +933,7 @@ module ASF
       end
     end
 
-    # remove people as owners of a project
+    # remove people as owners of a project in LDAP
     def remove_owners(people)
       if name == 'incubator'
         ASF::Project.find('incubator').remove_owners(people)
@@ -928,7 +942,7 @@ module ASF
       end
     end
 
-    # remove people as members of a project
+    # remove people as members of a project in LDAP
     def remove_committers(people)
       if name == 'incubator'
         ASF::Project.find('incubator').remove_members(people)
@@ -937,7 +951,7 @@ module ASF
       end
     end
 
-    # add people as owners of a project
+    # add people as owners of a project in LDAP
     def add_owners(people)
       if name == 'incubator'
         ASF::Project.find('incubator').add_owners(people)
@@ -946,7 +960,8 @@ module ASF
       end
     end
 
-    # add people as members of a project
+    # add people as committers of a project.  This information is stored
+    # in LDAP using a <tt>members</tt> attribute.
     def add_committers(people)
       if name == 'incubator'
         ASF::Project.find('incubator').add_members(people)
@@ -955,11 +970,12 @@ module ASF
       end
     end
 
+    # Designated Name from LDAP
     def dn
       @dn ||= ASF.search_one(base, "cn=#{name}", 'dn').first.first
     end
 
-    # remove people from a committee
+    # DEPRECATED remove people from a committee.  Call #remove_owners instead.
     def remove(people)
       @members = nil
       people = (Array(people) & members).map(&:dn)
@@ -968,7 +984,7 @@ module ASF
       @members = nil
     end
 
-    # add people to a committee
+    # DEPRECATED.  add people to a committee.  Call #add_owners instead.
     def add(people)
       @members = nil
       people = (Array(people) - members).map(&:dn)
@@ -977,7 +993,7 @@ module ASF
       @members = nil
     end
 
-    # add a new committee
+    # add a new committee to LDAP
     def self.add(name, people)
       entry = [
         mod_add('objectClass', ['groupOfNames', 'top']),
@@ -988,7 +1004,7 @@ module ASF
       ASF::LDAP.add("cn=#{name},#{base}", entry)
     end
 
-    # remove a committee
+    # remove a committee from LDAP
     def self.remove(name)
       ASF::LDAP.delete("cn=#{name},#{base}")
     end
diff --git a/lib/whimsy/asf/mail.rb b/lib/whimsy/asf/mail.rb
index 1405594..336d0d3 100644
--- a/lib/whimsy/asf/mail.rb
+++ b/lib/whimsy/asf/mail.rb
@@ -133,6 +133,11 @@ module ASF
   end
 
   class Committee
+    # mailing list for this committee.  Generally returns the first name in
+    # the dns (e.g. whimsical).  If so, it can be prefixed by a number of
+    # list names (e.g. dev, private) and <tt>.apache.org</tt> is to be
+    # appended.  In some cases, the name contains an <tt>@</tt> sign and
+    # is the fill name for the mail list.
     def mail_list
       case name.downcase
       when 'comdev'
diff --git a/lib/whimsy/asf/site.rb b/lib/whimsy/asf/site.rb
index 5675c82..c285b70 100644
--- a/lib/whimsy/asf/site.rb
+++ b/lib/whimsy/asf/site.rb
@@ -92,11 +92,13 @@ module ASF
 
 
   class Committee
+    # website for this committee.  Data is sourced from ASF::Site.
     def site
       site = ASF::Site.find(name)
       site[:link] if site
     end
 
+    # description for this committee.  Data is sourced from ASF::Site.
     def description
       site = ASF::Site.find(name)
       site[:text] if site

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

Mime
View raw message