From 4415331f16b7d61973b935ccb07adff29843dea5 Mon Sep 17 00:00:00 2001
From: pjht <pjht@users.noreply.github.com>
Date: Sun, 15 Jul 2018 16:39:31 -0500
Subject: [PATCH] Documentation work

---
 .yardopts              |  2 +-
 lib/rcircuit/adder.rb  |  6 +++++-
 lib/rcircuit/device.rb |  4 ++--
 lib/rcircuit/port.rb   |  3 ++-
 lib/rcircuit/vcd.rb    | 28 ++++++++++++++++++++--------
 todo.txt               |  1 -
 6 files changed, 30 insertions(+), 14 deletions(-)

diff --git a/.yardopts b/.yardopts
index f6020b9..cecd6d3 100644
--- a/.yardopts
+++ b/.yardopts
@@ -1 +1 @@
---private --exclude old/* 
+--private --protected --exclude old/* 
diff --git a/lib/rcircuit/adder.rb b/lib/rcircuit/adder.rb
index 0ab0fc8..803d552 100644
--- a/lib/rcircuit/adder.rb
+++ b/lib/rcircuit/adder.rb
@@ -1,4 +1,6 @@
+## Adder device
 class Adder < Device
+  # @param (see Device#initialize)
   def initialize(width, init_args)
     add_input("a", width)
     add_input("b", width)
@@ -7,7 +9,9 @@ class Adder < Device
     @mask=(2**width)-1
   end
 
-  def on_change(data_val)
+  private
+  # Called when there is a change to inputs
+  def on_change()
     out.setval((a.val+b.val)&@mask)
   end
 end
diff --git a/lib/rcircuit/device.rb b/lib/rcircuit/device.rb
index 5ef7826..17520d9 100644
--- a/lib/rcircuit/device.rb
+++ b/lib/rcircuit/device.rb
@@ -1,4 +1,4 @@
-# Class for devices such as adders and registers
+## Class for devices such as adders and registers
 class Device
   # Add an input port
   # @param name [String] Name of the port
@@ -7,7 +7,7 @@ class Device
   def add_input(name, width=1)
     port = Port.new(width)
     instance_variable_set("@#{name}", port)
-    port.add_callback { |val| on_change(val) }
+    port.add_callback { |val| on_change() }
   end
 
   # Add an output port
diff --git a/lib/rcircuit/port.rb b/lib/rcircuit/port.rb
index 0669214..939b38c 100644
--- a/lib/rcircuit/port.rb
+++ b/lib/rcircuit/port.rb
@@ -106,8 +106,9 @@ class Port
     return NotGate.new(self).out
   end
 
+  protected
+  
   # Used by connect when setting up bidirectional connection.
-  # @api private
   # @param (see #connect)
   # @return [void]
   def connect_back(port)
diff --git a/lib/rcircuit/vcd.rb b/lib/rcircuit/vcd.rb
index 42bfcc4..5257566 100644
--- a/lib/rcircuit/vcd.rb
+++ b/lib/rcircuit/vcd.rb
@@ -1,9 +1,8 @@
-# creates VCD file from port states
-
-require "set"
-
+## Creates VCD files from port states
 class VCD
 
+  # @param filename [String] The filename to output to
+  # @param timescale [String] The timescale
   def initialize(filename, timescale="1ps")
     @fd = File.open(filename, 'w')
     @time=0
@@ -11,9 +10,11 @@ class VCD
     @portmap = {}
     @idmap = {}
     @id = "a"
-    write_header
+    write_metadata
   end
 
+  # Start logging
+  # @return [void]
   def start
     @fd.puts "$scope module TOP $end"
     @portmap.each do |portname,port|
@@ -30,10 +31,16 @@ class VCD
     @fd.puts "\#0"
   end
 
-  def finish
+  # Stop logging
+  # @return [void]
+  def stop
     @fd.close
   end
 
+  # Attatch a port
+  # @param port [Port] The port to attatch
+  # @param portname [String] The name of the port in the VCD file
+  # @return [void]
   def attach(port, portname)
     raise ArgumentError.new("Duplicate port name '#{portname}'") if @portmap.has_key?(portname)
     if port.width > 1
@@ -47,6 +54,8 @@ class VCD
     end
   end
 
+  # Advance x timesteps
+  # @param timesteps [Integer] The number of timesteps to advance
   def advance(timesteps)
     @time += timesteps
     @fd.puts "\##{@time.to_s}"
@@ -54,14 +63,17 @@ class VCD
 
   private
 
-  def write_header
+  # Write the VCD file metadata
+  def write_metadata
     @fd.puts "$version\nRCircuit VCD Generator Version 0.0\n$end"
     @fd.puts "$date\n#{Time.now.asctime}\n$end"
     @fd.puts "$timescale #{@timescale} $end"
   end
 
+  # Writes VCD line for state of port, using id
+  # @param portname [String] the name of port to write out state
   def write_port_state(portname)
-    #writes VCD line for state of port, using id
+
     port = @portmap[portname]
     if port.width == 1
       state = port.val.to_s
diff --git a/todo.txt b/todo.txt
index 2c53019..d4d1b28 100644
--- a/todo.txt
+++ b/todo.txt
@@ -1,2 +1 @@
-Must document VCD and Adder
 Must add tests for VCD and Device