Start using Yard

- Add yard to Gemfile
- Configure .yardopts to pull in proper files
- Update custom docs to include yard metadata

.yardopts

@@ -0,0 +1,9 @@
+--title "Sapling Documentation"
+-
+README.md
+docs/config_file.md
+docs/config_file_example.md
+docs/editor.md
+CONTRIBUTING.md
+LICENSE
+lib/**.*.rb

README.md

@@ -1,3 +1,8 @@
+<!--
+# @markup markdown
+# @title README
+-->
+
 # Sapling: A Dialogue Tree CLI Utility
 
 Sapling allows for easy creation and use of dialogue trees.

docs/config_file.md

@@ -1,3 +1,8 @@
+<!--
+# @markup markdown
+# @title Configuration File
+-->
+
 # Configuration File Documentation
 
 The configuration file for `sapling` is a standard YAML file. The general

docs/config_file_example.md

@@ -0,0 +1,42 @@
+<!--
+# @markup markdown
+# @title Example YAML File
+-->
+# Example Dialogue Tree
+    ---
+    # The trunk is a general introduction to the tree. It shouldn't include any
+    # thematic details, rather a one-liner to let the user know what they're getting
+    # into.
+    -
+      trunk: "This is a general introduction to the dialogue tree."
+
+    # Branches are the content of a dialogue tree. Each branch is numbered, and that
+    # number is used as the primary means of navigation. The text of a branch is the
+    # story provided to the user; the result of getting to the branch. The leaves
+    # (the section titled leaf) represent the options. Options are displayed in the
+    # order they appear. Within a leaf, the text is what the option says, and the
+    # branch is the branch number which this option will lead to. Leading to branch
+    # number 0 will immediately exit the program.
+    #
+    # You can have as many branches and leaves as you wish, though having too many
+    # leaves may lead to both display problems, and paralyzing indecision.
+    -
+      branch:
+        number: 1
+        text: "The first branch. Displayed first, by default."
+        leaf:
+          -
+            text: "The first option for this branch. It leads to branch 2"
+            branch: 2
+          -
+            text: "The second branch. It immediately exits the program."
+            branch: 0
+
+    # A terminal branch is a branch which has no leaves. This represents an ending.
+    # Once a user hits a terminal branch, the program will display the branch text,
+    # and then redirect the user to branch 0, to exit.
+    -
+      branch:
+        number: 2
+        text: "This is a terminal branch. After displaying this text,
+          the program will exit."

docs/config_file_example.yaml

@@ -1,3 +1,4 @@
+# @title Example YAML File
 ---
 # The trunk is a general introduction to the tree. It shouldn't include any
 # thematic details, rather a one-liner to let the user know what they're getting

docs/editor.md

@@ -1,3 +1,7 @@
+<!--
+# @markup markdown
+# @title Using the Editor
+-->
 # Sapling Editor
 
 Sapling provides an editor for creating and modifying dialogue trees. The editor

lib/sapling.rb

@@ -9,7 +9,7 @@ module Gardner
   # Parse the branch
   #
   # @param tree [Array] The dialogue tree
-  # @return branches [Array] The array of options on the branch.
+  # @return [Array] The array of options on the branch.
   def self.prune_branches(tree)
     branches = { 0 => { "desc" => "Thanks for using Sapling!" } }
     tree.each do |b|
@@ -25,7 +25,7 @@ module Gardner
   # Parse the options
   #
   # @param leaves [Array] The option of leaf hashes
-  # @return options [Hash] A has of options
+  # @return [Hash] A has of options
   def self.prune_leaves(leaves)
     x = 1
     options = {}
@@ -45,7 +45,7 @@ module Gardner
   # The trunk is like the introduction to the tree.
   #
   # @param tree [Hash] The entire tree
-  # @return tree [Hash] The tree without the trunk
+  # @return [Hash] The tree without the trunk
   def self.prune_trunk(tree)
     trunk = tree.shift
     puts "Welcome to Sapling, a Dialogue Tree Utility.\n"
@@ -61,7 +61,7 @@ module Gardner
   # The main method for Sapling. From here, the tree is grown.
   #
   # @param file [File] The dialogue tree file
-  # @return branches [Hash] The final, constructed data set
+  # @return [Hash] The final, constructed data set
   def self.grow(file)
       tree = YAML.load_file(file[0])
       tree = Gardner.prune_trunk(tree)
@@ -73,7 +73,7 @@ module Gardner
   # Verify that a file is a dialogue tree file.
   #
   # @param file [File] The provided file
-  # @return status [Boolean] True if the file is a tree; false otherwise
+  # @return [Boolean] True if the file is a tree; false otherwise
   def self.verify_tree(file)
     results = []
     begin
@@ -97,7 +97,10 @@ end
 # Dialogue is the module for traversing an existing tree.
 module Dialogue
 
+  # Spealer holds the functionality for viewing and going through a dialogue
+  # tree.
   class Speaker
+    # The file, which should be a dialogue tree YAML file.
     attr_accessor :file
 
     def initialize
@@ -106,7 +109,6 @@ module Dialogue
 
     # Conversation handles navigating the tree, until the option to end is
     # reached.
-    #
     def conversation()
       tree = Gardner.grow(@file)
 
@@ -123,7 +125,7 @@ module Dialogue
     # Talk displays a branch, the options, and prompts for a response
     #
     # @param branch [Hash] A branch data set
-    # @return response [Integer] The number of the next branch
+    # @return [Integer] The number of the next branch
     def talk(branch)
       # If there are no options on this branch, we assume it's a terminal
       # branch. Return 0, and end the program.
@@ -165,56 +167,57 @@ module Planter
 
 end
 
-# Parsing is the class for option parsing, and the gateway to the program
+# Sapling is the main module for the program. From here, the rest of the world
-class Parsing
+# starts building.
+module Sapling
 
-  # Option parsing, and gateway to either reading and traversing a tree, or
+  # CLI is the class for option parsing, and the gateway to the program
-  # editing/creating a tree.
+  class CLI
-  #
-  # @params file [String] The location of the file to read, or write.
-  def talk(options)
-    opt_parser = OptionParser.new do |opt|
-      opt.banner = "Usage: sapling -t FILE\n" \
-                   "Usage: sapling -e [FILE]"
 
-      opt.on_tail("-h", "--help", "Show this menu") do
+    # Option parsing, and gateway to either reading and traversing a tree, or
-        puts opt
+    # editing/creating a tree.
+    def talk(options)
+      opt_parser = OptionParser.new do |opt|
+        opt.banner = "Usage: sapling -t FILE\n" \
+                     "Usage: sapling -e [FILE]"
+
+        opt.on_tail("-h", "--help", "Show this menu") do
+          puts opt
+          exit
+        end
+
+        opt.on("-t", "--talk",
+               "Begin traversing the provided dialogue tree") do
+
+          if ARGV.empty?
+            puts opt_parser
+            exit
+          end
+
+          unless Gardner.verify_tree(ARGV[0])
+            puts "\n#{opt}\n"
+            exit
+          end
+
+          speaker = Dialogue::Speaker.new
+          speaker.file = ARGV
+          speaker.conversation
+        end
+
+        opt.on("-e", "--edit",
+               "Create or edit a dialogue tree") do
+          puts "We gonna make a tree!"
+        end
+
+      end
+      opt_parser.parse!(options)
+
+      if ARGV.empty?
+        puts opt_parser
         exit
       end
-
-      opt.on("-t", "--talk",
-             "Begin traversing the provided dialogue tree") do
-
-        if ARGV.empty?
-          puts opt_parser
-          exit
-        end
-
-        unless Gardner.verify_tree(ARGV[0])
-          puts "\n#{opt}\n"
-          exit
-        end
-
-        speaker = Dialogue::Speaker.new
-        speaker.file = ARGV
-        speaker.conversation
-      end
-
-      opt.on("-e", "--edit",
-             "Create or edit a dialogue tree") do
-        puts "We gonna make a tree!"
-      end
-
     end
-    opt_parser.parse!(options)
-
-    if ARGV.empty?
-      puts opt_parser
-      exit
-    end
-
   end
-
 end
 
-Parsing.new.talk(ARGV)
+Sapling::CLI.new.talk(ARGV)