You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@whimsical.apache.org by se...@apache.org on 2025/03/14 01:00:15 UTC
(whimsy) branch master updated: Api doc updates (#265)
This is an automated email from the ASF dual-hosted git repository.
sebb 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 e02634e5 Api doc updates (#265)
e02634e5 is described below
commit e02634e57f76723eb1c3ae4e26a86959568129d7
Author: Shane Curcuru <as...@shanecurcuru.org>
AuthorDate: Thu Mar 13 21:00:10 2025 -0400
Api doc updates (#265)
* Ensure rDocs format; minor docco improvements.
* tweak docco
* Docco: list key convenience methods
---
lib/whimsy/asf.rb | 20 +++++++++----
lib/whimsy/asf/agenda.rb | 3 +-
lib/whimsy/asf/auth.rb | 2 ++
lib/whimsy/asf/board.rb | 1 +
lib/whimsy/asf/documents.rb | 4 +--
lib/whimsy/asf/json-utils.rb | 7 ++---
lib/whimsy/asf/ldap.rb | 66 ++++++++++++++++++++----------------------
lib/whimsy/asf/mail.rb | 2 +-
lib/whimsy/asf/meeting-util.rb | 4 +--
lib/whimsy/asf/memapps.rb | 7 ++---
lib/whimsy/asf/member-files.rb | 4 ++-
lib/whimsy/asf/member.rb | 1 +
lib/whimsy/asf/mlist.rb | 7 ++---
lib/whimsy/asf/petri.rb | 3 +-
lib/whimsy/asf/site-img.rb | 4 +--
lib/whimsy/asf/status.rb | 4 +--
lib/whimsy/asf/svn.rb | 15 ++++++++--
lib/whimsy/asf/time-utils.rb | 2 --
lib/whimsy/public.rb | 8 ++---
lib/whimsy/sitestandards.rb | 4 +--
20 files changed, 88 insertions(+), 80 deletions(-)
diff --git a/lib/whimsy/asf.rb b/lib/whimsy/asf.rb
index c638e47f..b4c54250 100644
--- a/lib/whimsy/asf.rb
+++ b/lib/whimsy/asf.rb
@@ -18,13 +18,21 @@ require_relative 'asf/themes'
require_relative 'asf/site-img'
#
-# The ASF module contains a set of classes which encapsulate access to a number
-# of data sources such as LDAP, ICLAs, auth lists, etc. This code originally
-# was developed as a part of separate tools and was later refactored out into a
-# common library. Some of the older tools don't fully make use of this
-# refactoring.
+# The ASF module contains a set of classes which encapsulate access to many
+# public and private data sources across the ASF, as well as synthesizing
+# some useful convenience functions and data structures, like representing
+# a PMC as a Committee with list of People and the Chair.
+#
+# Key data access classes include:
+# SVN, Git, ICLA, LDAP, Authorization
+#
+# Key classes that provide complex data structures:
+# Person, Committer, Member, Committee, Podling, OrgChart, Board
+#
+# This code originally was developed as a part of separate tools and was later
+# refactored out into this common library. Many Whimsy tools, but not all, make
+# use of various ASF:: features and convenience methods.
#
-
module ASF
# Last modified time of any file in the entire source tree.
def self.library_mtime
diff --git a/lib/whimsy/asf/agenda.rb b/lib/whimsy/asf/agenda.rb
index b4d59422..840a4c15 100644
--- a/lib/whimsy/asf/agenda.rb
+++ b/lib/whimsy/asf/agenda.rb
@@ -14,7 +14,8 @@ module ASF
end
#
-# Class which contains a number of parsers.
+# Board::Agenda contains various parsers for an entire board agenda.txt
+# file, as well as for various agenda section types.
#
class ASF::Board::Agenda
# mapping of agenda section numbers to section names
diff --git a/lib/whimsy/asf/auth.rb b/lib/whimsy/asf/auth.rb
index a88675d8..e0a4b02c 100644
--- a/lib/whimsy/asf/auth.rb
+++ b/lib/whimsy/asf/auth.rb
@@ -1,5 +1,7 @@
module ASF
+ # Convenience methods to determine svn auth for a user.
+ #
# parse the <tt>-authorization-template</tt> files contained within
# <tt>infrastructure-puppet/modules/subversion_server/files/authorization</tt>
class Authorization
diff --git a/lib/whimsy/asf/board.rb b/lib/whimsy/asf/board.rb
index 07d48df6..6f7632e5 100644
--- a/lib/whimsy/asf/board.rb
+++ b/lib/whimsy/asf/board.rb
@@ -3,6 +3,7 @@ require 'active_support'
require 'active_support/time'
module ASF
+ # Utility methods for board agendas or meetings.
module Board
TIMEZONE = ActiveSupport::TimeZone.new('UTC')
diff --git a/lib/whimsy/asf/documents.rb b/lib/whimsy/asf/documents.rb
index 07d86aec..25e4e57d 100644
--- a/lib/whimsy/asf/documents.rb
+++ b/lib/whimsy/asf/documents.rb
@@ -1,9 +1,7 @@
require 'json'
-# Access to documents/* (except member_apps)
-
module ASF
-
+ # Caching and convenience methods for files in documents/* (except member_apps)
module DocumentUtils # This module is also used for member_apps
MAX_AGE = 600 # 5 minutes
diff --git a/lib/whimsy/asf/json-utils.rb b/lib/whimsy/asf/json-utils.rb
index 90c40b96..3a2096e2 100644
--- a/lib/whimsy/asf/json-utils.rb
+++ b/lib/whimsy/asf/json-utils.rb
@@ -1,9 +1,6 @@
-# JSON utilities
-
-# This addon must be required before use
-
require 'json'
-
+# Utility functions for comparing JSON data.
+# This addon must be required before use
module ASFJSON
# Compare JSON files
# bc = breadcrumb
diff --git a/lib/whimsy/asf/ldap.rb b/lib/whimsy/asf/ldap.rb
index 28ea8b5d..44b136bc 100644
--- a/lib/whimsy/asf/ldap.rb
+++ b/lib/whimsy/asf/ldap.rb
@@ -1,36 +1,3 @@
-#
-# Encapsulate access to LDAP, caching results for performance. For best
-# performance in applications that access large number of objects, make use
-# of the preload methods to pre-fetch multiple objects in a single LDAP
-# call, and rely on the cache to find the objects later.
-#
-# The cache makes heavy use of Weak References internally to enable garbage
-# collection to reclaim objects; among other things, this ensures that
-# LDAP results don't become too stale.
-#
-# Until garbage collection reclaims an object, calls to find methods for the
-# same name is guaranteed to return the same object. Holding on to the
-# results of find or preload calls (by assigning it to a variable) is
-# sufficient to prevent reclaiming of objects.
-#
-# To illustrate, the following is likely to return the same id twice, followed
-# by a new id:
-# puts ASF::Person.find('rubys').__id__
-# puts ASF::Person.find('rubys').__id__
-# GC.start
-# puts ASF::Person.find('rubys').__id__
-#
-# By contrast, the following is guaranteed to produce the same id three times:
-# rubys1 = ASF::Person.find('rubys')
-# rubys2 = ASF::Person.find('rubys')
-# GC.start
-# rubys3 = ASF::Person.find('rubys')
-# puts [rubys1.__id__, rubys2.__id__, rubys3.__id__]
-#
-
-# Note: custom ASF LDAP attributes are defined in the file:
-# https://github.com/apache/infrastructure-p6/blob/production/modules/ldapserver/files/asf-custom.schema
-
require 'wunderbar'
require 'ldap'
require 'weakref'
@@ -44,9 +11,40 @@ if __FILE__ == $0
require 'whimsy/asf/config'
end
+# Note: custom ASF LDAP attributes are defined in the file:
+# https://github.com/apache/infrastructure-p6/blob/production/modules/ldapserver/files/asf-custom.schema
+
module ASF
@@weakrefs = Set.new
-
+ #
+ # Encapsulate access to LDAP, caching results for performance. For best
+ # performance in applications that access large number of objects, make use
+ # of the preload methods to pre-fetch multiple objects in a single LDAP
+ # call, and rely on the cache to find the objects later.
+ #
+ # The cache makes heavy use of Weak References internally to enable garbage
+ # collection to reclaim objects; among other things, this ensures that
+ # LDAP results don't become too stale.
+ #
+ # Until garbage collection reclaims an object, calls to find methods for the
+ # same name is guaranteed to return the same object. Holding on to the
+ # results of find or preload calls (by assigning it to a variable) is
+ # sufficient to prevent reclaiming of objects.
+ #
+ # To illustrate, the following is likely to return the same id twice, followed
+ # by a new id:
+ # puts ASF::Person.find('rubys').__id__
+ # puts ASF::Person.find('rubys').__id__
+ # GC.start
+ # puts ASF::Person.find('rubys').__id__
+ #
+ # By contrast, the following is guaranteed to produce the same id three times:
+ # rubys1 = ASF::Person.find('rubys')
+ # rubys2 = ASF::Person.find('rubys')
+ # GC.start
+ # rubys3 = ASF::Person.find('rubys')
+ # puts [rubys1.__id__, rubys2.__id__, rubys3.__id__]
+ #
module LDAP
# Mutex preventing simultaneous connections to LDAP from a single process
CONNECT_LOCK = Mutex.new
diff --git a/lib/whimsy/asf/mail.rb b/lib/whimsy/asf/mail.rb
index bbf8aa05..9351df39 100644
--- a/lib/whimsy/asf/mail.rb
+++ b/lib/whimsy/asf/mail.rb
@@ -1,7 +1,7 @@
require 'weakref'
module ASF
-
+ # Convenience functions related to emails or mailing lists.
class Mail
# return a Hash containing complete list of all known emails, and the
# ASF::Person that is associated with that email.
diff --git a/lib/whimsy/asf/meeting-util.rb b/lib/whimsy/asf/meeting-util.rb
index 7ffa1061..c4edb36b 100644
--- a/lib/whimsy/asf/meeting-util.rb
+++ b/lib/whimsy/asf/meeting-util.rb
@@ -1,12 +1,12 @@
#!/usr/bin/env ruby
-# Utility methods and structs related to Member's Meetings
-# NOTE: Assumes 21st century '2*'
$LOAD_PATH.unshift '/srv/whimsy/lib' if __FILE__ == $PROGRAM_NAME
require 'whimsy/asf'
require 'json'
require 'date'
module ASF
+ # Utility methods and structs related to Member's Meetings.
+ # NOTE: Assumes 21st century '2*' for meeting directories.
class MeetingUtil
RECORDS = ASF::SVN.svnurl!('Meetings') # in SVN
MEETINGS_DIR = ASF::SVN['Meetings'] # local checkout
diff --git a/lib/whimsy/asf/memapps.rb b/lib/whimsy/asf/memapps.rb
index 3c29cbaf..8b8ee8d7 100644
--- a/lib/whimsy/asf/memapps.rb
+++ b/lib/whimsy/asf/memapps.rb
@@ -1,13 +1,12 @@
-#
-# Common access to membership application files
-#
-
### INITIAL RELEASE - SUBJECT TO CHANGE ###
require_relative 'config'
require_relative 'svn'
module ASF
+ #
+ # Common access to membership application files
+ #
class MemApps
@@files = nil
@@tag = nil
diff --git a/lib/whimsy/asf/member-files.rb b/lib/whimsy/asf/member-files.rb
index 8040c7ab..e9564da2 100644
--- a/lib/whimsy/asf/member-files.rb
+++ b/lib/whimsy/asf/member-files.rb
@@ -7,7 +7,9 @@ require_relative 'ldap'
require_relative 'svn'
module ASF
-
+ #
+ # Common access to various Member Meeting data.
+ #
class MemberFiles
NOMINATED_MEMBERS = 'nominated-members.txt'
diff --git a/lib/whimsy/asf/member.rb b/lib/whimsy/asf/member.rb
index 6640cfaa..93a06745 100644
--- a/lib/whimsy/asf/member.rb
+++ b/lib/whimsy/asf/member.rb
@@ -2,6 +2,7 @@ require 'weakref'
require 'wunderbar'
module ASF
+ # Convenience class for Person who is an ASF Member.
class Member
include Enumerable
@@text = nil
diff --git a/lib/whimsy/asf/mlist.rb b/lib/whimsy/asf/mlist.rb
index 91e554a5..826dd5c0 100644
--- a/lib/whimsy/asf/mlist.rb
+++ b/lib/whimsy/asf/mlist.rb
@@ -5,11 +5,10 @@ require 'weakref'
require 'whimsy/asf/config'
module ASF
-
+ # utility methods for handling mailing list attributes:
+ # - subscriptions
+ # - moderation
module MLIST
- # utility methods for handling mailing list attributes:
- # - subscriptions
- # - moderation
# whilst the source files are not particularly difficult to parse, it makes
# sense to centralise access so any necessary changes can be localised
diff --git a/lib/whimsy/asf/petri.rb b/lib/whimsy/asf/petri.rb
index 7d6d412c..874b0235 100644
--- a/lib/whimsy/asf/petri.rb
+++ b/lib/whimsy/asf/petri.rb
@@ -2,11 +2,10 @@ require 'yaml'
require 'net/http'
module ASF
+ PETRI_INFO = 'https://petri.apache.org/info.yaml'
# Represents a Petri culture
# currently defined in
# https://petri.apache.org/info.yaml
-
- PETRI_INFO = 'https://petri.apache.org/info.yaml'
class Petri
include Enumerable
diff --git a/lib/whimsy/asf/site-img.rb b/lib/whimsy/asf/site-img.rb
index c761e672..955633d5 100644
--- a/lib/whimsy/asf/site-img.rb
+++ b/lib/whimsy/asf/site-img.rb
@@ -1,7 +1,7 @@
# Find site image files
module ASF
-
+ # Utility method for listing site images (icons, etc.)
class SiteImage
def self.listnames
_, list = ASF::SVN.getlisting('site-img')
@@ -12,4 +12,4 @@ module ASF
listnames.select{|file| file =~ /^#{id}.*\.(svg|eps|ai|pdf)$/}.first
end
end
-end
\ No newline at end of file
+end
diff --git a/lib/whimsy/asf/status.rb b/lib/whimsy/asf/status.rb
index 3c207062..c47c907d 100644
--- a/lib/whimsy/asf/status.rb
+++ b/lib/whimsy/asf/status.rb
@@ -1,11 +1,9 @@
#!/usr/bin/env ruby
-# status methods
-
require 'socket'
require 'resolv'
-# common methods
+# Cache and display various status indicators about the live server.
module Status
ACTIVE_HOSTNAME = 'whimsy.apache.org'
diff --git a/lib/whimsy/asf/svn.rb b/lib/whimsy/asf/svn.rb
index a14ee9e2..aed86ef9 100644
--- a/lib/whimsy/asf/svn.rb
+++ b/lib/whimsy/asf/svn.rb
@@ -7,8 +7,19 @@ require 'tempfile'
module ASF
#
- # Provide access to files stored in Subversion, generally to local working
- # copies that are updated via cronjobs.
+ # Provide access to files stored in Subversion, either to local working
+ # copies that are updated via cronjobs, or to files checked out and
+ # potentially updated or created via user action in a tool.
+ #
+ # Allows for conceptually mapping specific directories in common ASF
+ # SVN repositories via the repository.yml mapping file.
+ #
+ # == Key SVN methods
+ #
+ # - SVN.svn allows building an svn command; see also option:dryrun
+ # - SVN.svn! variant that raises Exception on error
+ # - SVN.svn_ variant in Wunderbar contexts for web output
+ # - SVN.update allows user action to update or create a new file
#
# Note: svn paths passed to various #find methods are resolved relative to
# <tt>https://svn.apache.org/repos/</tt> if they are not full URIs.
diff --git a/lib/whimsy/asf/time-utils.rb b/lib/whimsy/asf/time-utils.rb
index d4ad65cb..0993ab45 100644
--- a/lib/whimsy/asf/time-utils.rb
+++ b/lib/whimsy/asf/time-utils.rb
@@ -1,7 +1,5 @@
# Time/date utilities
-
# This addon must be required before use
-
module ASFTime
# Convert seconds to number of days, hours or minutes
# Intended for countdown-style displays
diff --git a/lib/whimsy/public.rb b/lib/whimsy/public.rb
index 87d0e55a..dff9281d 100644
--- a/lib/whimsy/public.rb
+++ b/lib/whimsy/public.rb
@@ -1,11 +1,9 @@
-#
-# Simplify access to JSON files in the /public/ directory
-#
-
require 'json'
require 'net/https'
require 'fileutils'
-
+#
+# Simplify access to JSON files in the /public/ directory
+#
module Public
# location of where public files are placed on the web
DATAURI = 'https://whimsy.apache.org/public/'
diff --git a/lib/whimsy/sitestandards.rb b/lib/whimsy/sitestandards.rb
index f8913b98..1f853195 100644
--- a/lib/whimsy/sitestandards.rb
+++ b/lib/whimsy/sitestandards.rb
@@ -1,8 +1,6 @@
#!/usr/bin/env ruby
# Defines partial standards for Apache website checker
-# TODO better document with specific policies
-
-# Encapsulate (most) scans/validations done on website content
+# TODO better document individual scans with specific policies
module SiteStandards
extend self
CHECK_TEXT = 'text' # (optional) Regex of <a ...>Text to scan for</a>, of a.text.downcase.strip