Improve API documentation (#38)

- Add `Readers::Reader` and `Serializer::Serializer` base classes 
- Make all readers/serializers extend from their corresponding base classes
- Better docs with `Reader`/`Serializer` and generics
- Fix all code blocks from `\`` to `+` and add some more
- Add `@return [void]` where appropriate
- Add `@return [self]` where appropriate
- Fix `Nodes::Node` duplicate and broken references
- Fix some typos and add some missing periods

lib/rambling/trie.rb

@@ -10,12 +10,12 @@
 
 # General namespace for all Rambling gems.
 module Rambling
-  # Entry point for rambling-trie API.
+  # Entry point for +rambling-trie+ API.
   module Trie
     class << self
-      # Creates a new Rambling::Trie. Entry point for the Rambling::Trie API.
+      # Creates a new +Rambling::Trie+. Entry point for the +rambling-trie+ API.
       # @param [String, nil] filepath the file to load the words from.
-      # @param [Reader, nil] reader the file parser to get each word.
+      # @param [Readers::Reader, nil] reader the file parser to get each word.
       # @return [Container] the trie just created.
       # @yield [Container] the trie just created.
       # @see Rambling::Trie::Readers Readers.
@@ -36,7 +36,7 @@ def create filepath = nil, reader = nil
 
       # Loads an existing trie from disk into memory. By default, it will
       # deduce the correct way to deserialize based on the file extension.
-      # Available formats are `yml`, `marshal`, and `zip` versions of all the
+      # Available formats are +yml+, +marshal+, and +zip+ versions of all the
       # previous formats. You can also define your own.
       # @param [String] filepath the file to load the words from.
       # @param [Serializer, nil] serializer the object responsible of loading
@@ -46,7 +46,7 @@ def create filepath = nil, reader = nil
       # @see Rambling::Trie::Serializers Serializers.
       # @note Use of
       #   {https://ruby-doc.org/core-2.7.0/Marshal.html#method-c-load
-      #   Marshal.load} is generally discouraged. Only use the `.marshal`
+      #   Marshal.load} is generally discouraged. Only use the +.marshal+
       #   format with trusted input.
       def load filepath, serializer = nil
         serializer ||= serializers.resolve filepath
@@ -58,19 +58,21 @@ def load filepath, serializer = nil
 
       # Dumps an existing trie from memory into disk. By default, it will
       # deduce the correct way to serialize based on the file extension.
-      # Available formats are `yml`, `marshal`, and `zip` versions of all the
+      # Available formats are +yml+, +marshal+, and +zip+ versions of all the
       # previous formats. You can also define your own.
       # @param [Container] trie the trie to dump into disk.
       # @param [String] filepath the file to dump to serialized trie into.
-      # @param [Serializer, nil] serializer the object responsible of
+      # @param [Serializers::Serializer, nil] serializer the object responsible
+      #   for trie serialization.
+      # @return [void]
       #   serializing and dumping the trie into disk.
-      # @see Rambling::Trie::Serializers Serializers.
+      # @see Serializers Serializers.
       def dump trie, filepath, serializer = nil
         serializer ||= serializers.resolve filepath
         serializer.dump trie.root, filepath
       end
 
-      # Provides configuration properties for the Rambling::Trie gem.
+      # Provides configuration properties for the +Rambling::Trie+ gem.
       # @return [Configuration::Properties] the configured properties of the
       #   gem.
       # @yield [Configuration::Properties] the configured properties of the

lib/rambling/trie/comparable.rb

@@ -6,8 +6,8 @@ module Trie
     module Comparable
       # Compares two nodes.
       # @param [Nodes::Node] other the node to compare against.
-      # @return [Boolean] `true` if the nodes' {Nodes::Node#letter #letter} and
-      #   {Nodes::Node#children_tree #children_tree} are equal, `false`
+      # @return [Boolean] +true+ if the nodes' {Nodes::Node#letter #letter} and
+      #   {Nodes::Node#children_tree #children_tree} are equal, +false+
       #   otherwise.
       def == other
         letter == other.letter &&

lib/rambling/trie/compressible.rb

@@ -6,8 +6,8 @@ module Trie
     module Compressible
       # Indicates if the current {Rambling::Trie::Nodes::Node Node} can be
       # compressed or not.
-      # @return [Boolean] `true` for non-{Nodes::Node#terminal? terminal} nodes
-      #   with one child, `false` otherwise.
+      # @return [Boolean] +true+ for non-{Nodes::Node#terminal? terminal} nodes
+      #   with one child, +false+ otherwise.
       def compressible?
         !(root? || terminal?) && 1 == children_tree.size
       end

lib/rambling/trie/configuration/properties.rb

@@ -6,26 +6,26 @@ module Configuration
       # Provides configurable properties for Rambling::Trie.
       class Properties
         # The configured {Readers Readers}.
-        # @return [ProviderCollection] the mapping of configured {Readers
-        #   Readers}.
+        # @return [ProviderCollection<Readers::Reader>] the mapping of
+        #   configured {Readers Readers}.
         attr_reader :readers
 
         # The configured {Serializers Serializers}.
-        # @return [ProviderCollection] the mapping of configured {Serializers
-        #   Serializers}.
+        # @return [ProviderCollection<Serializers::Serializer>] the mapping of
+        #   configured {Serializers Serializers}.
         attr_reader :serializers
 
         # The configured {Compressor Compressor}.
         # @return [Compressor] the configured compressor.
         attr_accessor :compressor
 
-        # The configured root_builder, which should return a {Nodes::Node Node}
-        #   when called.
-        # @return [Proc<Nodes::Node>] the configured root_builder.
+        # The configured +root_builder+, which returns a {Nodes::Node Node}
+        # when called.
+        # @return [Proc<Nodes::Node>] the configured +root_builder+.
         attr_accessor :root_builder
 
-        # The configured tmp_path, which will be used for throwaway files.
-        # @return [String] the configured tmp_path.
+        # The configured +tmp_path+, which will be used for throwaway files.
+        # @return [String] the configured +tmp_path+.
         attr_accessor :tmp_path
 
         # Returns a new properties instance.
@@ -34,6 +34,7 @@ def initialize
         end
 
         # Resets back to default properties.
+        # @return [void]
         def reset
           reset_readers
           reset_serializers

lib/rambling/trie/configuration/provider_collection.rb

@@ -6,7 +6,7 @@ module Configuration
       # Collection of configurable providers.
       class ProviderCollection
         # The name of this provider collection.
-        # @return [String] the name of this provider collection.
+        # @return [Symbol] the name of this provider collection.
         attr_reader :name
 
         # @overload default
@@ -15,18 +15,18 @@ class ProviderCollection
         # @overload default=(provider)
         #   Sets the default provider. Needs to be one of the configured
         #   providers.
-        #   @param [Object] provider the provider to use as default.
+        #   @param [TProvider] provider the provider to use as default.
         #   @raise [ArgumentError] when the given provider is not in the
         #     provider collection.
-        #   @note If no providers have been configured, `nil` will be assigned.
-        # @return [Object, nil] the default provider to use when a provider
+        #   @note If no providers have been configured, +nil+ will be assigned.
+        # @return [TProvider, nil] the default provider to use when a provider
         #   cannot be resolved in {ProviderCollection#resolve #resolve}.
         attr_reader :default
 
         # Creates a new provider collection.
-        # @param [String] name the name for this provider collection.
-        # @param [Hash] providers the configured providers.
-        # @param [Object] default the configured default provider.
+        # @param [Symbol] name the name for this provider collection.
+        # @param [Hash<Symbol, TProvider>] providers the configured providers.
+        # @param [TProvider, nil] default the configured default provider.
         def initialize name, providers = {}, default = nil
           @name = name
           @configured_providers = providers
@@ -38,8 +38,9 @@ def initialize name, providers = {}, default = nil
         # Adds a new provider to the provider collection.
         # @param [Symbol] extension the extension that the provider will
         #   correspond to.
-        # @param [provider] provider the provider to add to the provider
+        # @param [TProvider] provider the provider to add to the provider
         #   collection.
+        # @return [TProvider] the provider just added.
         def add extension, provider
           providers[extension] = provider
         end
@@ -54,21 +55,22 @@ def default= provider
         end
 
         # List of configured providers.
-        # @return [Hash] the mapping of extensions to their corresponding
-        #   providers.
+        # @return [Hash<Symbol, TProvider>] the mapping of extensions to their
+        #   corresponding providers.
         def providers
           @providers ||= {}
         end
 
         # Resolves the provider from a filepath based on the file extension.
         # @param [String] filepath the filepath to resolve into a provider.
-        # @return [Object] the provider corresponding to the file extension in
-        #   this provider collection. {#default} if not found.
+        # @return [TProvider, nil] the provider for the given file's extension.
+        #   {#default} if not found.
         def resolve filepath
           providers[file_format filepath] || default
         end
 
         # Resets the provider collection to the initial values.
+        # @return [void]
         def reset
           providers.clear
           configured_providers.each { |k, v| self[k] = v }
@@ -85,7 +87,7 @@ def formats
 
         # Get provider corresponding to a given format.
         # @param [Symbol] format the format to search for in the collection.
-        # @return [Object] the provider corresponding to that format.
+        # @return [TProvider] the provider corresponding to that format.
         # @see https://ruby-doc.org/core-2.7.0/Hash.html#method-i-5B-5D
         #   Hash#[]
         def [] format

lib/rambling/trie/container.rb

@@ -13,7 +13,7 @@ class Container
       # Creates a new trie.
       # @param [Nodes::Node] root the root node for the trie
       # @param [Compressor] compressor responsible for compressing the trie
-      # @yield [Container] the trie just created.
+      # @yield [self] the trie just initialized.
       def initialize root, compressor
         @root = root
         @compressor = compressor
@@ -44,7 +44,7 @@ def concat words
       # Compresses the existing trie using redundant node elimination. Marks
       # the trie as compressed. Does nothing if the trie has already been
       # compressed.
-      # @return [Container] self
+      # @return [self]
       # @note This method replaces the root {Nodes::Raw Raw} node with a
       #   {Nodes::Compressed Compressed} version of it.
       def compress!
@@ -65,20 +65,18 @@ def compress
 
       # Checks if a path for a word or partial word exists in the trie.
       # @param [String] word the word or partial word to look for in the trie.
-      # @return [Boolean] `true` if the word or partial word is found, `false`
+      # @return [Boolean] +true+ if the word or partial word is found, +false+
       #   otherwise.
-      # @see Nodes::Raw#partial_word?
-      # @see Nodes::Compressed#partial_word?
+      # @see Nodes::Node#partial_word?
       def partial_word? word = ''
         root.partial_word? word.chars
       end
 
       # Checks if a whole word exists in the trie.
       # @param [String] word the word to look for in the trie.
-      # @return [Boolean] `true` only if the word is found and the last
-      #   character corresponds to a terminal node, `false` otherwise.
-      # @see Nodes::Raw#word?
-      # @see Nodes::Compressed#word?
+      # @return [Boolean] +true+ only if the word is found and the last
+      #   character corresponds to a terminal node, +false+ otherwise.
+      # @see Nodes::Node#word?
       def word? word = ''
         root.word? word.chars
       end
@@ -87,8 +85,7 @@ def word? word = ''
       # @param [String] word the word to look for in the trie.
       # @return [Array<String>] all the words contained in the trie that start
       #   with the specified characters.
-      # @see Nodes::Raw#scan
-      # @see Nodes::Compressed#scan
+      # @see Nodes::Node#scan
       def scan word = ''
         root.scan(word.chars).to_a
       end
@@ -99,29 +96,29 @@ def scan word = ''
       # @return [Enumerator<String>] all the words in the given string that
       #   match a word in the trie.
       # @yield [String] each word found in phrase.
-      # @see Nodes::Node#words_within
       def words_within phrase
         words_within_root(phrase).to_a
       end
 
       # Checks if there are any valid words in a given string.
       # @param [String] phrase the string to look for matching words in.
-      # @return [Boolean] `true` if any word within phrase is contained in the
-      #   trie, `false` otherwise.
+      # @return [Boolean] +true+ if any word within phrase is contained in the
+      #   trie, +false+ otherwise.
       # @see Container#words_within
       def words_within? phrase
         words_within_root(phrase).any?
       end
 
       # Compares two trie data structures.
       # @param [Container] other the trie to compare against.
-      # @return [Boolean] `true` if the tries are equal, `false` otherwise.
+      # @return [Boolean] +true+ if the tries are equal, +false+ otherwise.
       def == other
         root == other.root
       end
 
       # Iterates over the words contained in the trie.
       # @yield [String] the words contained in this trie node.
+      # @return [self]
       def each
         return enum_for :each unless block_given?
 
@@ -152,17 +149,17 @@ def children
       end
 
       # Root node's children tree.
-      # @return [Array<Nodes::Node>] the array of children nodes contained in
-      #   the root node.
+      # @return [Hash<Symbol, Nodes::Node>] the children tree hash contained in
+      #   the root node, consisting of +:letter => node+.
       # @see Nodes::Node#children_tree
       def children_tree
         root.children_tree
       end
 
       # Indicates if the root {Nodes::Node Node} can be
       # compressed or not.
-      # @return [Boolean] `true` for non-{Nodes::Node#terminal? terminal}
-      #    nodes with one child, `false` otherwise.
+      # @return [Boolean] +true+ for non-{Nodes::Node#terminal? terminal}
+      #    nodes with one child, +false+ otherwise.
       def compressed?
         root.compressed?
       end

lib/rambling/trie/enumerable.rb

@@ -13,6 +13,7 @@ module Enumerable
 
       # Iterates over the words contained in the trie.
       # @yield [String] the words contained in this trie node.
+      # @return [self]
       def each
         return enum_for :each unless block_given?
 

lib/rambling/trie/nodes/compressed.rb

@@ -9,14 +9,14 @@ class Compressed < Rambling::Trie::Nodes::Node
         # trying to add a word to the current compressed trie node
         # @param [String] _ the word to add to the trie.
         # @raise [InvalidOperation] if the trie is already compressed.
-        # @return [nil] this never returns as it always raises an exception.
+        # @return [void]
         def add _
           raise Rambling::Trie::InvalidOperation,
             'Cannot add word to compressed trie'
         end
 
-        # Always return `true` for a compressed node.
-        # @return [Boolean] always `true` for a compressed node.
+        # Always return +true+ for a compressed node.
+        # @return [Boolean] always +true+ for a compressed node.
         def compressed?
           true
         end