Added a whole bunch of yard documentation.

lib/nntp.rb

@@ -4,7 +4,30 @@
 require "nntp/connection"
 require 'nntp/ssl_connection'
 
+# The main entry point for this module is the open method.
+#
+# ::open returns an object that is an active NNTP session.
+# If a block is passed to it, the session object is made available
+# therein.
 module NNTP
+  # The main entrypoint to the module.
+  #
+  # @option options :url The URL of the NNTP server.
+  # @option options :port (119/563) The port number of the server.
+  # @option options [Boolean] :ssl (false) Connect via SSL?
+  # @option options [Hash] :auth Authentication credentials and style.
+  # @example Basic connection
+  #   nntp = NNTP.open(
+  #     :url => 'nntp.example.org',
+  #     :auth => {:user => 'mike', :pass => 'soopersecret'}
+  #   )
+  #   nntp.quit
+  # @example Pass a block
+  #   # Automatically closes connection
+  #   NNTP.open(:url => 'nntp.example.org') do |nntp|
+  #     nntp.group = 'alt.bin.foo'
+  #   end
+  # @return [NNTP::Session] the active NNTP session
   def self.open(options)
     if options[:ssl]
       connection = SSLConnection.new(options)
@@ -23,4 +46,4 @@ def self.open(options)
       session
     end
   end
-end
+end

lib/nntp/connection.rb

@@ -2,13 +2,51 @@
 require 'nntp/status'
 
 module NNTP
+  #  Handles communication with the NNTP server.
+  #
+  #  Most communication with an NNTP server happens in a back-and-forth
+  #  style.
+  #
+  #  The client sends a message to the server.  The server will respond with a status response, and sometimes with extra data. See {https://tools.ietf.org/html/rfc3977 RFC 3977} for more details.
+  #
+  #  This class handles this communication by providing two methods,
+  #  one for use when additional data is expected, and one for when it is not.
   class Connection
+    # @!attribute [r] socket
+    #   The object upon which all IO takes place.
+    #
+    # @!attribute [r] status
+    #   The most status of the most recent command.
+    #   @return [NNTP::Status]
+
     attr_reader :socket, :status
 
+    # (see #build_socket)
     def initialize(options)
       @socket = build_socket(options)
     end
 
+    # Sends a message to the server, collects the the status and additional data, if successful.
+    # A Hash is returned containing two keys: :status and :data.
+    # :status is an {NNTP::Status}, and :data is an array containing
+    # the lines from the response See example for details.
+    # @example
+    #   nntp.query(:list) do |status, data|
+    #     $stdout.puts status
+    #     data.each? do |line|
+    #       $stdout.puts line
+    #     end
+    #   end
+    #
+    #   => 215 Information follows
+    #   => alt.bin.foo
+    #   => alt.bin.bar
+    # @param query [Symbol, String] The command to send
+    # @param args Any additional parameters are passed along with the command.
+    # @yield The status and data from the server.
+    # @yieldparam status [NNTP::Status]
+    # @yieldparam data [Array<String>, nil] An array with the lines from the server.  Nil if the query failed.
+    # @return [Hash] The status and requested data.
     def query(query, *args)
       command = form_message(query, args)
       send_message(command)
@@ -22,17 +60,24 @@ def query(query, *args)
       {:status => status, :data => data}
     end
 
+    # Sends a message to the server and collects the status response.
+    # @param (see #query)
+    # @return [NNTP::Status] The server's response.
     def command(command, *args)
       command = form_message(command, args)
       send_message(command)
       get_status
     end
 
+    # Fetch a status line from the server.
+    # @return [NNTP::Status]
     def get_status
       code, message = get_line.split(' ', 2)
       @status = status_factory(code.to_i, message)
     end
 
+    # Sends "QUIT\\r\\n" to the server, disconnects the socket.
+    # @return [void]
     def quit
       command(:quit)
       socket.close
@@ -78,4 +123,4 @@ def status_factory(*args)
       NNTP::Status.new(*args)
     end
   end
-end
+end

lib/nntp/session.rb

@@ -2,8 +2,14 @@
 require 'nntp/message'
 
 module NNTP
+  # Most of the action happens here.  This class describes the
+  # object the user interacts with the most.
+  # It is constructed by NNTP::open, but you can build your own
+  # if you like.
   class Session
     attr_reader :connection, :group
+    # @option options [NNTP::Connection, NNTP::SSLConnection] :connection
+    #   The connection object.
     def initialize(options)
       @group = nil
       @connection = options.fetch(:connection) do
@@ -12,15 +18,31 @@ def initialize(options)
       check_initial_status
     end
 
+    # Authenticate to the server.
+    #
+    # @option args :user Username
+    # @option args :pass Password
+    # @option args :type (:standard)
+    #   Which authentication type to use.  Currently only
+    #   standard is supported.
+    # @return [NNTP::Status]
     def auth(args)
       auth_method = args.fetch(:type, :standard)
       standard_auth(args) if auth_method == :standard
     end
 
+    # Fetches and returns the list of groups from the server or, if it
+    # has already been fetched, returns the saved list.
+    # @return [Array<NNTP::Group>]
     def groups
       @groups ||= fetch_groups
     end
 
+    # @!attribute [rw] group
+    #   Retrieves current group, or
+    #   sets current group, server-side, to assigned value.
+    #   @param [String] group_name The name of the group to be selected.
+    #   @return [NNTP::Group] The current group.
     def group=(group_name)
       connection.command(:group, group_name)
       if status[:code] == 211
@@ -29,6 +51,12 @@ def group=(group_name)
       end
     end
 
+    # Fetch list of message numbers from a given group.
+    # @param group  The name of the group to list defaults to {#group #group.name}
+    # @param range (nil) If given, specifies the range of messages to retrieve
+    # @return [Array<NNTP::Message>] The list of messages
+    #   (only the message numbers will be populated).
+    # @see https://tools.ietf.org/html/rfc3977#section-6.1.2
     def listgroup(*args)
       messages = []
       connection.query(:listgroup, *args) do |status, data|
@@ -43,6 +71,9 @@ def listgroup(*args)
       messages
     end
 
+    # Fetch list of messages from current group.
+    # @return [Array<NNTP::Message>] The list of messages
+    #   (The numbers AND the subjects will be populated).
     def subjects
       subjects = []
       range ="#{group[:first_message]}-"
@@ -58,10 +89,12 @@ def subjects
       subjects
     end
 
+    # The most recent status from the server.
     def status
       connection.status
     end
 
+    # (see NNTP::Connection#quit)
     def quit
       connection.quit
     end
@@ -103,4 +136,4 @@ def fetch_groups
       group_list
     end
   end
-end
+end

NNTPClient.gemspec → nntp-client.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'nntp/version'
 
 Gem::Specification.new do |gem|
-  gem.name          = "nntp"
+  gem.name          = "nntp-client"
   gem.version       = NNTP::VERSION
   gem.authors       = ["Michael Westbom"]
   gem.email         = %w(totallymike@gmail.com)