Commits

Michael Granger committed 87bc5aa

De-Yard, docs cleanup.

  • Participants
  • Parent commits ad2d90b

Comments (0)

Files changed (11)

 ^release\.(notes|ann)$
 ~$
 \.DS_Store$
+^doc/

File History.md

-## 0.0.1 [2011-03-22] Michael Granger <ged@FaerieMUD.org>
-
-Initial release.
-

File History.rdoc

+## 0.0.1 [2011-03-22] Michael Granger <ged@FaerieMUD.org>
+
+Initial release.
+

File Manifest.txt

 ChangeLog
-History.md
+History.rdoc
 LICENSE
 Manifest.txt
-README.md
+README.rdoc
 Rakefile
 examples/homedirservice.rb
 examples/rubyversion.rb

File README.md

-# drbservice
-
-* https://bitbucket.org/ged/drbservice
-
-## Description
-
-DRbService is a framework we use at LAIKA for creating authenticated
-SSL-encrypted DRb services that provide access to privileged operations
-without the need to give shell access to everyone.
-
-There are a few examples in the `examples/` directory of the gem, which
-are stripped-down versions of the services we actually use.
-
-The current implementation is kind of a hack, but I intend to 
-eventually finish a DRb protocol that does the same thing in a more
-elegant, less-hackish way, as well as a tool that can generate 
-a new service along with support files for one of several different 
-runtime environments.
-
-If you're curious, see the `drb/authsslprotocol.rb` file for the 
-protocol. This will replace the current method-hiding code in 
-`drbservice.rb`, but existing services should be able to switch over
-quite easily. Or that's the intention.
-
-
-## Installation
-
-    gem install drbservice
-
-
-## Contributing
-
-You can check out the current development source with Mercurial via its
-[Bitbucket project][bitbucket]. Or if you prefer Git, via 
-[its Github mirror][github].
-
-After checking out the source, run:
-
-    $ rake newb
-
-This task will install any missing dependencies, run the tests/specs,
-and generate the API documentation.
-
-
-## License
-
-Copyright (c) 2010, 2011, Michael Granger
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice,
-  this list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
-
-* Neither the name of the author/s, nor the names of the project's
-  contributors may be used to endorse or promote products derived from this
-  software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-
-[bitbucket]: https://bitbucket.org/ged/drbservice
-[github]: https://github.com/ged/drbservice
+= drbservice
+
+* https://bitbucket.org/ged/drbservice
+
+== Description
+
+DRbService is a framework we use at LAIKA for creating authenticated
+SSL-encrypted DRb services that provide access to privileged operations
+without the need to give shell access to everyone.
+
+There are a few examples in the `examples/` directory of the gem, which
+are stripped-down versions of the services we actually use.
+
+The current implementation is kind of a hack, but I intend to 
+eventually finish a DRb protocol that does the same thing in a more
+elegant, less-hackish way, as well as a tool that can generate 
+a new service along with support files for one of several different 
+runtime environments.
+
+If you're curious, see the `drb/authsslprotocol.rb` file for the 
+protocol. This will replace the current method-hiding code in 
+`drbservice.rb`, but existing services should be able to switch over
+quite easily. Or that's the intention.
+
+
+== Installation
+
+    gem install drbservice
+
+
+== Contributing
+
+You can check out the current development source with Mercurial via its
+{Bitbucket project}[https://bitbucket.org/ged/drbservice]. Or if you prefer Git, via 
+{its Github mirror}[https://github.com/ged/drbservice].
+
+After checking out the source, run:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the API documentation.
+
+
+== License
+
+Copyright (c) 2010, 2011, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
 #!/usr/bin/env rake
 
-require 'hoe'
+begin
+	require 'hoe'
+rescue LoadError
+	abort "This Rakefile requires 'hoe' (gem install hoe)"
+end
 
 Hoe.plugin :mercurial
-Hoe.plugin :yard
 Hoe.plugin :signing
 
 Hoe.plugins.delete :rubyforge
 
 hoespec = Hoe.spec 'drbservice' do
-	self.readme_file = 'README.md'
-	self.history_file = 'History.md'
+	self.readme_file = 'README.rdoc'
+	self.history_file = 'History.rdoc'
+	self.extra_rdoc_files << 'README.rdoc' << 'History.rdoc'
 
 	self.developer 'Michael Granger', 'ged@FaerieMUD.org'
 
-	self.extra_dev_deps.push *{
-		'rspec' => '~> 2.4',
-	}
+	self.dependency 'rspec', '~> 2.6', :developer
 
 	self.spec_extras[:licenses] = ["BSD"]
 	self.spec_extras[:post_install_message] = %{

File lib/drb/authsslprotocol.rb

 		SCHEME = 'drbauthssl'
 
 
-		### Parse a drbauthssl:// URI
-		### @param [String, URI, #host, #port, #query] uri  the URI to parse
-		### @return [Array<String, Fixnum, Hash>]  The values from the URI as an Array of
-		###     the form: [ host, port, optionhash ].
-		### @raise [DRbBadScheme] if the +uri+ is not a +drbauthssl+ URI
-		### @raise [DRbBadURI] if the +uri+ is not a valid +drbauthssl+ URI
+		### Parse a drbauthssl:// URI. Accepts a String, a URI, or any object that responds to 
+		### #host, #port, and #query.
+		### Return the values from the URI as an Array of the form: [ host, port, optionhash ].
+		### Raises DRbBadScheme if the +uri+ is not a +drbauthssl+ URI.
+		### Raises DRbBadURI if the +uri+ is missing the port number.
 		def self::parse_uri( uri )
 			uri = URI( uri ) unless uri.respond_to?( :host )
 			raise DRbBadScheme, "not a #{SCHEME} URI: %p" % [ uri ] unless 

File lib/drbservice.rb

 require 'drb/ssl'
 
 
-# A base class for DRb-based services.
-# @abstract Concrete subclasses must define the service API by declaring 
-#   public methods. By default, any public methods are hidden until the client 
-#   authenticates. You can optionally declare a subset of its API that is
-#   accessible before authentication by wrapping them in an 'unguarded' block. 
-# @see DRbService::unguarded
+# A base class for DRb-based services. Concrete subclasses must define the service API by 
+# declaring public methods. By default, any public methods are hidden until the client 
+# authenticates. You can optionally declare a subset of its API that is # accessible before 
+# authentication by wrapping them in an 'unguarded' block. # See DRbService::unguarded for 
+# more details. 
 class DRbService
 	require 'drbservice/utils'
 	include DRbUndumped,
 	###	C L A S S   M E T H O D S
 	#################################################################
 
-	### Start the DRbService at the given +ip+ and +port+.
-	### @param [Hash] config     the service configuration hash
-	### @option config [String]  :ip       the ip to bind to
-	### @option config [Fixnum]  :port     the port to listen on
-	### @option config [String]  :certfile the name of the server's SSL certificate file
-	### @option config [String]  :keyfile  the name of the server's SSL key file
-	### @return [void]
+	### Start the DRbService, using the ip, port, and cert information from the given +config+ 
+	### hash.
+	###
+	### [:ip]       the ip to bind to
+	### [:port]     the port to listen on
+	### [:certfile] the name of the server's SSL certificate file
+	### [:keyfile]  the name of the server's SSL key file
+	### 
 	def self::start( config={} )
 		config = DEFAULT_CONFIG.merge( config )
 
 	end
 
 
-	### Obscure any instance method added while not in 'unguarded' mode.
-	### @param [Symbol] meth  the name of the method being added
-	### @return [void]
+	### Method-addition callback: Obscure the method +meth+ unless unguarded mode is enabled.
 	def self::method_added( meth )
 		super
 
 
 
 	### Inheritance callback: Add a per-class 'unguarded mode' flag to subclasses.
-	### @param [Class] subclass  the inheriting subclass
-	### @return [void]
 	def self::inherited( subclass )
 		self.log.debug "Setting @unguarded_mode in %p" % [ subclass ]
 		subclass.instance_variable_set( :@unguarded_mode, false )
 
 	### Declare some service methods that can be called without authentication in
 	### the provided block.
-	### @return [void]
 	def self::unguarded
 		self.unguarded_mode = true
 		yield
 
 		# The unguarded mode flag -- instance methods defined while this flag is set
 		# will not be hidden
-		# @return [Boolean] 
 		attr_accessor :unguarded_mode
 
 	end
 	#################################################################
 
 	### Create a new instance of the service.
-	### @raise [ScriptError] if DRbService is instantiated directly
+	### Raises a ScriptError if DRbService is instantiated directly.
 	def initialize( config={} )
 		raise ScriptError,
 			"can't instantiate #{self.class} directly: please subclass it instead" if

File lib/drbservice/ldapauth.rb

 	end
 
 
-	# @return [String] the username of the authenticated user
+	# the username of the authenticated user
 	attr_reader :authuser
 
-	# @return [Treequel::Branch] the branch of the authenticated user
+	# the Treequel::Branch of the authenticated user
 	attr_reader :authuser_branch
 
 
 	protected
 	#########
 
-	### Find the specified +username+ entry in the given +directory+.
-	### 
-	### @param [Treequel::Directory] directory  the directory to search
-	### @param [String] username                the name to use in the search
-	### 
-	### @return [Treequel::Branch, nil]  the first found user, if one was found
+	### Find the specified +username+ entry in the given +directory+, which should be a 
+	### Treequel::Directory. Returns the Treequel::Branch for the first found user, if one 
+	### was found, or +nil+ if no such user was found.
 	def find_auth_user( directory, username )
 		self.log.debug "Finding the user to bind as."
 

File lib/drbservice/utils.rb

 
 		### Inclusion callback: Add logging methods and instance variables to
 		### the Module +mod+.
-		### @param [Module] mod  the including Class or Module
 		def self::included( mod )
 
 			# Logging class instance variables