Merge pull request #400 from BallAerospace/code_cleanup

Fix YARD documentation. Change editted to edited

lib/cosmos/conversions/conversion.rb

@@ -9,10 +9,8 @@
 # attribution addendums as found in the LICENSE.txt
 
 module Cosmos
-
   # Performs a general conversion via the implementation of the call method
   class Conversion
-
     # @return [Symbol] The converted data type. Must be one of
     #   {Cosmos::StructureItem#data_type}
     attr_reader :converted_type
@@ -42,12 +40,10 @@ def to_s
       self.class.to_s.split('::')[-1]
     end
 
-    # @param (see Conversion#to_config)
+    # @param read_or_write [String] Either 'READ' or 'WRITE'
     # @return [String] Config fragment for this conversion
     def to_config(read_or_write)
       "    #{read_or_write}_CONVERSION #{self.class.name.class_name_to_filename}\n"
     end
-
-  end # class Conversion
-
-end # module Cosmos
+  end
+end

lib/cosmos/core_ext/class.rb

@@ -32,14 +32,16 @@ class Class
   #   MyClass.test # returns "Test"
   #
   # @param args [Array<Symbol>] Array of symbols which should be turned into
-  #   instance variables with class method accessors
+  #   instance variables with class method readers
   def instance_attr_reader(*args)
     args.each do |arg|
       self.class_eval("def #{arg};@#{arg};end")
       self.instance_eval("def #{arg};self.instance.#{arg};end")
     end
   end
 
+  # @param args [Array<Symbol>] Array of symbols which should be turned into
+  #   instance variables with class method accessors (read and write)
   def instance_attr_accessor(*args)
     args.each do |arg|
       self.class_eval("def #{arg};@#{arg};end")

lib/cosmos/core_ext/file.rb

@@ -12,6 +12,7 @@
 
 # COSMOS specific additions to the Ruby File class
 class File
+  # Non printable ASCII characters
   NON_ASCII_PRINTABLE = /[^\x21-\x7e\s]/
 
   # @return [Boolean] Whether the file only contains ASCII characters

lib/cosmos/core_ext/io.rb

@@ -13,9 +13,23 @@
 class IO
   include CosmosIO
 
+  # Initial timeout to call IO.select with. Timeouts are increased by doubling
+  # this value until the SELET_MAX_TIMEOUT value is reached.
   SELECT_BASE_TIMEOUT = 0.0004
+  # The maximum timeout at which point we call IO.select with whatever
+  # remaining timeout is left.
   SELECT_MAX_TIMEOUT = 0.016
 
+  # The method is identical to IO.select but instead of calling IO.select with
+  # the full timeout, it calls IO.select with a small timeout and then
+  # doubles the timeout twice until eventually it calls IO.select with the
+  # remaining passed in timeout value.
+  # TODO: Ryan why was this originally done?
+  #
+  # @param read_sockets [Array<IO>] IO objects to wait to be ready to read
+  # @param write_sockets [Array<IO>] IO objects to wait to be ready to write
+  # @param error_array [Array<IO>] IO objects to wait for exceptions
+  # @param timeout [Numeric] Number of seconds to wait
   def self.fast_select(read_sockets = nil, write_sockets = nil, error_array = nil, timeout = nil)
     # Always try a zero timeout first
     current_timeout = SELECT_BASE_TIMEOUT
@@ -65,10 +79,14 @@ def self.fast_select(read_sockets = nil, write_sockets = nil, error_array = nil,
     end # while true
   end # fast_select
 
+  # @param read_sockets [Array<IO>] IO objects to wait to be ready to read
+  # @param timeout [Numeric] Number of seconds to wait
   def self.fast_read_select(read_sockets, timeout)
     return fast_select(read_sockets, nil, nil, timeout)
   end
 
+  # @param write_sockets [Array<IO>] IO objects to wait to be ready to write
+  # @param timeout [Numeric] Number of seconds to wait
   def self.fast_write_select(write_sockets, timeout)
     return fast_select(nil, write_sockets, nil, timeout)
   end

lib/cosmos/core_ext/time.rb

@@ -339,7 +339,7 @@ def self.ccsds2julian(day, ms, us)
     (day + JULIAN_DATE_OF_CCSDS_EPOCH) + ((ms.to_f + (us / 1000.0)) / MSEC_PER_DAY_FLOAT)
   end
 
-  # @param [Float] julian date
+  # @param jdate [Float] julian date
   # @return [Array<day, ms, us>] Julian converted to CCSDS
   def self.julian2ccsds(jdate)
     day = jdate - JULIAN_DATE_OF_CCSDS_EPOCH
@@ -363,8 +363,8 @@ def self.ccsds2sec(day, ms, us, sec_epoch_jd = JULIAN_DATE_OF_CCSDS_EPOCH)
     (self.ccsds2julian(day, ms, us) - sec_epoch_jd) * SEC_PER_DAY_FLOAT
   end
 
-  # @param seconds [Float]
-  # @param sec_epoch_jd [Float] Epoch to of seconds value
+  # @param sec [Float] Number of seconds to convert
+  # @param sec_epoch_jd [Float] Epoch of seconds value
   # @return [Array<day, ms, us>] CCSDS date
   def self.sec2ccsds(sec, sec_epoch_jd = JULIAN_DATE_OF_CCSDS_EPOCH)
     self.julian2ccsds((sec / SEC_PER_DAY_FLOAT) + sec_epoch_jd)

lib/cosmos/gui/dialogs/about_dialog.rb

@@ -9,37 +9,38 @@
 # attribution addendums as found in the LICENSE.txt
 
 module Cosmos
-  # Help->About dialog which is part of all COSMOS tools. Displays the license
-  # information, version information, path information, application
-  # information, and general COSMOS information. Also provides a backdoor to a
-  # PRY dialog to aid in debugging.
+  # Help->About dialog which is part of all COSMOS tools. Displays the license,
+  # software versions, environment variables, and general COSMOS information.
+  # Also provides a backdoor to a PRY dialog to aid in debugging. See
+  # {PryDialog} for more details.
   class AboutDialog < Qt::Dialog
-    ABOUT_COSMOS = ''
-    ABOUT_COSMOS << "COSMOS application icons are courtesy of http://icons8.com.\n"
-    ABOUT_COSMOS << "COSMOS application sounds are courtesy of http://www.freesfx.co.uk.\n"
-    ABOUT_COSMOS << "\n"
-    ABOUT_COSMOS << "COSMOS utilizes the QtRuby (http://rubyforge.org/projects/korundum) library under "
-    ABOUT_COSMOS << "the GNU Lesser General Public License. QtRuby is a Ruby extension module that provides an "
-    ABOUT_COSMOS << "interface to the Qt Gui Toolkit (http://qt-project.org) by Digia "
-    ABOUT_COSMOS << "under the GNU Lesser General Public License.\n"
-    ABOUT_COSMOS << "\n"
-    ABOUT_COSMOS << "Ruby Version: ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE} patchlevel #{RUBY_PATCHLEVEL}) [#{RUBY_PLATFORM}]\n"
-    ABOUT_COSMOS << "Rubygems Version: #{Gem::VERSION}\n"
-    ABOUT_COSMOS << "Qt Version: #{Qt::qVersion}\n"
-    ABOUT_COSMOS << "Cosmos::PATH: #{Cosmos::PATH}\n"
-    ABOUT_COSMOS << "Cosmos::USERPATH: #{Cosmos::USERPATH}\n"
-    ABOUT_COSMOS << "\n"
-    ABOUT_COSMOS << "Environment Variables:\n"
-    ABOUT_COSMOS << "RUBYLIB: #{ENV['RUBYLIB']}\n"
-    ABOUT_COSMOS << "RUBYOPT: #{ENV['RUBYOPT']}\n"
-    ABOUT_COSMOS << "GEM_PATH: #{ENV['GEM_PATH']}\n"
-    ABOUT_COSMOS << "GEM_HOME: #{ENV['GEM_HOME']}\n"
-    ABOUT_COSMOS << "\n"
-    ABOUT_COSMOS << "Loaded Gems:\n"
+    # About text to display in the dialog
+    ABOUT_COSMOS = "COSMOS application icons are courtesy of http://icons8.com.\n"\
+      "COSMOS application sounds are courtesy of http://www.freesfx.co.uk.\n"\
+      "\n"\
+      "COSMOS utilizes the QtRuby (http://rubyforge.org/projects/korundum) "\
+      "library under the GNU Lesser General Public License. "\
+      "QtRuby is a Ruby extension module that provides an "\
+      "interface to the Qt Gui Toolkit (http://qt-project.org) by Digia "\
+      "under the GNU Lesser General Public License.\n\n"\
+      "Ruby Version: ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE} "\
+      "patchlevel #{RUBY_PATCHLEVEL}) [#{RUBY_PLATFORM}]\n"\
+      "Rubygems Version: #{Gem::VERSION}\n"\
+      "Qt Version: #{Qt::qVersion}\n"\
+      "Cosmos::PATH: #{Cosmos::PATH}\n"\
+      "Cosmos::USERPATH: #{Cosmos::USERPATH}\n\n"\
+      "Environment Variables:\n"\
+      "RUBYLIB: #{ENV['RUBYLIB']}\n"\
+      "RUBYOPT: #{ENV['RUBYOPT']}\n"\
+      "GEM_PATH: #{ENV['GEM_PATH']}\n"\
+      "GEM_HOME: #{ENV['GEM_HOME']}\n\n"\
+      "Loaded Gems:\n"
     Gem.loaded_specs.values.map {|x| ABOUT_COSMOS << "#{x.name} #{x.version} #{x.platform}\n"}
 
     @@pry_dialogs = []
 
+    # @param parent [Qt::Widget] Part of the dialog (the application)
+    # @param about_string [String] Application specific informational text
     def initialize(parent, about_string)
       super(parent, Qt::WindowTitleHint | Qt::WindowSystemMenuHint)
       @saved_text = ''
@@ -131,6 +132,8 @@ def initialize(parent, about_string)
       dispose()
     end
 
+    # Register key press events to listen for 'p', 'r', 'y' and popup a {PryDialog}
+    # @param event [Qt::Event] The keypress event
     def keyPressEvent(event)
       @saved_text << event.text.to_s
       if @saved_text[0] == 'p'

lib/cosmos/gui/dialogs/calendar_dialog.rb

@@ -14,17 +14,16 @@
 require 'cosmos'
 
 module Cosmos
-
-  # CalendarDialog class
-  #
+  # Creates a dialog with a date and optional time selection
   class CalendarDialog < Qt::Dialog
-
-    # The selected time
+    # @return [Time] User entered time
     attr_reader :time
 
-    # Constructor
-    def initialize (parent, title, initial_time = nil, show_time = true)
-      # Call base class constructor
+    # @param parent [Qt::Widget] Parent of this dialog
+    # @param title [String] Dialog title
+    # @param initial_time [Time] Initial time to display
+    # @param show_time [Boolean] Whether to display the time selection
+    def initialize(parent, title, initial_time = nil, show_time = true)
       super(parent)
       setWindowTitle(title)
 
@@ -90,13 +89,12 @@ def initialize (parent, title, initial_time = nil, show_time = true)
       @layout.addLayout(@button_layout)
 
       setLayout(@layout)
-    end # def initialize
+    end
 
     protected
 
     # Handler for the OK button being pressed - builds the time object
     def handle_ok_button
-      # Get calendar selected day
       @date = @calendar.selectedDate
 
       # Reduce @time to time at midnight of day
@@ -130,7 +128,5 @@ def handle_calendar_select
       @date = @calendar.selectedDate
       @year_month_day.setText(sprintf("%04u/%02u/%02u", @date.year, @date.month, @date.day))
     end
-
-  end # class CalendarDialog
-
-end # module Cosmos
+  end
+end

lib/cosmos/gui/dialogs/cmd_details_dialog.rb

@@ -15,8 +15,9 @@
 require 'cosmos/gui/dialogs/details_dialog'
 
 module Cosmos
-
+  # Creates a dialog which shows the details of the given command.
   class CmdDetailsDialog < DetailsDialog
+    # (see DetailsDialog#initialize)
     def initialize(parent, target_name, packet_name, item_name)
       super(parent, target_name, packet_name, item_name)
 
@@ -45,8 +46,6 @@ def initialize(parent, target_name, packet_name, item_name)
       rescue DRb::DRbConnError
         # Just do nothing
       end
-
     end
-  end # class CmdDetailsDialog
-
-end # module Cosmos
+  end
+end

lib/cosmos/gui/dialogs/cmd_tlm_raw_dialog.rb

@@ -15,19 +15,27 @@
 require 'cosmos/gui/qt'
 
 module Cosmos
-
+  # Creates a dialog showing a packet formatted as a binary hex dump
   class RawDialog < Qt::Dialog
     slots 'packet_update_timeout()'
 
+    # Constant to indicate a command packet dump
     CMD_TYPE = 'cmd'
+    # Constant to indicate a telemetry packet dump
     TLM_TYPE = 'tlm'
+    # Dialog update period
     PACKET_UPDATE_PERIOD_MS = 1000
-    HEADER1 = "Address   Data                                             Ascii\n"
-    HEADER2 = "---------------------------------------------------------------------------\n"
-    HEADER  = HEADER1 + HEADER2
+    # Header string to display over the dump
+    HEADER = "Address   Data                                             Ascii\n"\
+             "---------------------------------------------------------------------------\n"
 
+    # @return [Qt::Font] Font to display the dialog dump (should be monospaced)
     @@font = nil
 
+    # @param parent [Qt::Dialog] Parent for the dialog
+    # @param type [String] Dialog type which must be 'cmd' or 'tlm'
+    # @param target_name [String] Name of the target
+    # @param packet_name [String] Name of the packet
     def initialize(parent, type, target_name, packet_name)
       super(parent, Qt::WindowTitleHint | Qt::WindowSystemMenuHint)
       raise "RawDialog: Undefined type:#{type}" if type != CMD_TYPE and type != TLM_TYPE
@@ -97,6 +105,7 @@ def initialize(parent, type, target_name, packet_name)
       end
     end
 
+    # Callback to get the latest packet and update the dialog
     def packet_update_timeout
       if (@type == CMD_TYPE)
         packet = System.commands.packet(@target_name, @packet_name)
@@ -115,35 +124,40 @@ def packet_update_timeout
 
     def reject
       super()
-      if @timer
-        @timer.stop
-        @timer.dispose
-        @timer = nil
-      end
+      stop_timer if @timer
       self.dispose
     end
 
     def closeEvent(event)
       super(event)
-      if @timer
-        @timer.stop
-        @timer.dispose
-        @timer = nil
-      end
+      stop_timer if @timer
       self.dispose
     end
-  end # class RawDialog
 
+    def stop_timer
+      @timer.stop
+      @timer.dispose
+      @timer = nil
+    end
+  end
+
+  # Creates a dialog which displays a command packet as a hex dump
   class CmdRawDialog < RawDialog
+    # @param parent (see RawDialog#initialize)
+    # @param target_name (see RawDialog#initialize)
+    # @param packet_name (see RawDialog#initialize)
     def initialize(parent, target_name, packet_name)
       super(parent, RawDialog::CMD_TYPE, target_name, packet_name)
     end
   end
 
+  # Creates a dialog which displays a telemetry packet as a hex dump
   class TlmRawDialog < RawDialog
+    # @param parent (see RawDialog#initialize)
+    # @param target_name (see RawDialog#initialize)
+    # @param packet_name (see RawDialog#initialize)
     def initialize(parent, target_name, packet_name)
       super(parent, RawDialog::TLM_TYPE, target_name, packet_name)
     end
   end
-
-end # module Cosmos
+end