Documentation improvements

lib/nmea_plus.rb

@@ -3,14 +3,16 @@
 require 'nmea_plus/generated_parser/parser'
 require 'nmea_plus/generated_parser/tokenizer'
 
-# NMEAPlus contains classes for parsing and decoding NMEA and AIS messages.
-# You probably want to check out {NMEAPlus::Message::NMEA::NMEAMessage}
-# and {NMEAPlus::Message::AIS::AISMessage}.
+# NMEAPlus contains classes for parsing and decoding NMEA and AIS messages, of which the {NMEAPlus::SourceDecoder}
+# is most relevant.  Parsed messages extend from the {Message::NMEA::NMEAMessage} object, and any binary
+# AIS playloads are decoded into objects that extend from {Message::AIS::AISMessage}.
 # @author Ian Katz
 module NMEAPlus
 
-  # The NMEA source decoder wraps an IO object, converting each_line functionality
-  # to {#each_message} or {#each_complete_message}
+  # The SourceDecoder is meant as the primary entry point into the {NMEAPlus} module.
+  # It wraps a {Decoder} object and an IO object, converting IO's #each_line functionality
+  # to {#each_message} and/or {#each_complete_message},
+  # which yield {NMEAPlus::Message} objects representing the parsed data.
   class SourceDecoder
     # False by default.
     # @return [bool] whether to throw an exception on lines that don't properly parse
@@ -30,9 +32,20 @@ def initialize(line_reader)
       @decoder = NMEAPlus::Decoder.new
     end
 
-    # Executes the block for every valid NMEA message in the source stream
+    # Executes the block for every valid NMEA message in the source stream.
+    # In practice, you should use {#each_complete_message} unless you have a very compelling reason not to.
     # @yield [NMEAPlus::Message] A parsed message
     # @return [void]
+    # @example
+    #   input = "$GPGGA,123519,4807.038,N,01131.000,W,1,08,0.9,545.4,M,46.9,M,2.2,123*4b"
+    #   io_source = StringIO.new(input)  # source decoder works on any IO object
+    #   source_decoder = NMEAPlus::SourceDecoder.new(io_source)
+    #   source_decoder.each_message do |message|
+    #     if "GGA" == message.interpreted_data_type
+    #       puts "Latitude: #{message.latitude} / Longitude: #{message.longtitude}"
+    #       # prints "Latitude: 48.1173 / Longitude: -11.516666666666666666"
+    #     end
+    #   end
     def each_message
       @source.each_line do |line|
         if @throw_on_parse_fail
@@ -49,10 +62,22 @@ def each_message
       end
     end
 
-    # Executes the block for every valid NMEA message in the source stream, attempting to
-    # group multipart messages into message chains.
+    # Attempts to group multipart NMEA messages into chains, and executes the block once for every complete chain.
+    #
     # @yield [NMEAPlus::Message] A parsed message that may contain subsequent parts
     # @return [void]
+    # @example
+    #   input1 = "!AIVDM,2,1,0,A,58wt8Ui`g??r21`7S=:22058<v05Htp000000015>8OA;0sk,0*7B"
+    #   input2 = "!AIVDM,2,2,0,A,eQ8823mDm3kP00000000000,2*5D"
+    #   io_source = StringIO.new("#{input1}\n#{input2}")  # source decoder works on any IO object
+    #   source_decoder = NMEAPlus::SourceDecoder.new(io_source)
+    #   source_decoder.each_complete_message do |message|
+    #     if message.ais && message.ais.message_type == 5
+    #       ais = message.ais  # ais payload shortcut
+    #       puts "Ship with MMSI #{ais.source_mmsi} (#{ais.name.strip}) is going to #{ais.destination.strip}"
+    #       # prints "Ship with MMSI 603916439 (ARCO AVON) is going to HOUSTON"
+    #     end
+    #   end
     def each_complete_message
       partials = {}  # hash of message type to message-chain-in-progress
       each_message do |msg|

lib/nmea_plus/message/ais/vdm_payload/mmsi_info.rb

@@ -4,7 +4,8 @@ module Message
     module AIS
       module VDMPayload
 
-        # A container for MMSI information, all of which can be assumed from the MMSI value itself
+        # A container for MMSI (Maritime Mobile Service Identity) information,
+        # all of which is indicated from the MMSI integer value itself.
         class MMSIInfo
 
           # The MMSI
@@ -17,7 +18,7 @@ def initialize(mmsi)
           end
 
           # The MMSI category as defined by ITU-R M.585-7
-          # @!parse attr_reader :mmsi_category
+          # @!parse attr_reader :category
           # @return [Symbol] The symbol for the MMSI category
           def category
             case id.to_s.rjust(9, '0') # formatted as 9 digit string with leading 0s
@@ -69,7 +70,8 @@ def category_description
             end
           end
 
-          # The MMSI Maritime Identification Digits (MID)
+          # The MMSI Maritime Identification Digits (MID), indicating country codes as specified by the ITU.
+          # http://www.itu.int/online/mms/glad/cga_mids.sh
           # @!parse attr_reader :mid
           # @return [Integer] the MID
           def mid
@@ -86,7 +88,7 @@ def mid
             id.to_s.rjust(9, '0')[range].to_i
           end
 
-          # The ISO 3166-1 indicated by the MMSI Maritime Identification Digits (MID)
+          # The ISO 3166-1 country ID indicated by the MMSI Maritime Identification Digits (MID)
           # @!parse attr_reader :country_id
           # @return [Integer] the MID
           def country_id

parser/tokenizer.rex

@@ -1,6 +1,6 @@
 
 module NMEAPlus
-class Decoder < Parser  # The source file is in .rex format -- indentation and most yard documentation is impossible.  The class does a very basic parse of an input line, calling {NMEAPlus::MessageFactory.create} on the result.  In parser.y, this is currently defined to be a {NMEAPlus::NMEAMessageFactory} if the line begins with `$` and {NMEAPlus::AISMessageFactory} if the line begins with `!`
+class Decoder < Parser  # The source file is in .rex format -- indentation and most yard documentation is impossible.  This class does a very basic parse of an input line, calling {NMEAPlus::MessageFactory.create} on the result.  In parser.y, this is currently defined to be a {NMEAPlus::NMEAMessageFactory} if the line begins with `$` and {NMEAPlus::AISMessageFactory} if the line begins with `!`.  In pratice, you should be using {NMEAPlus::SourceDecoder} (which wraps this class) to parse messages from an IO object; this class can only parse individual strings.
 
 macro
   csum      \*[0-9A-F]{2}