updating documentation

CHANGELOG.rdoc

@@ -1,3 +1,9 @@
+=== HEAD
+
+* 1 major enhancement
+
+  * Switched from FFI to a C backend
+
 === 1.0.0 / 2009-06-01
 
 * 1 major enhancement

ext/nfc/nfc_device.c

@@ -1,5 +1,11 @@
 #include <nfc_device.h>
 
+/*
+ * call-seq:
+ *  connect
+ *
+ * Connect to the NFC device
+ */
 static VALUE connect(VALUE klass)
 {
   dev_info * dev = nfc_connect();
@@ -9,6 +15,12 @@ static VALUE connect(VALUE klass)
   return Data_Wrap_Struct(klass, 0, 0, dev);
 }
 
+/*
+ * call-seq:
+ *  disconnect
+ *
+ * Disconnect from the NFC device
+ */
 static VALUE disconnect(VALUE self)
 {
   dev_info * dev;
@@ -18,6 +30,12 @@ static VALUE disconnect(VALUE self)
   return self;
 }
 
+/*
+ * call-seq:
+ *  configure(option, value)
+ *
+ * Configure the Device with +option+ and +value+
+ */
 static VALUE configure(VALUE self, VALUE option, VALUE flag)
 {
   dev_info * dev;
@@ -32,6 +50,12 @@ static VALUE configure(VALUE self, VALUE option, VALUE flag)
   return self;
 }
 
+/*
+ * call-seq:
+ *  select(tag)
+ *
+ * Select the +tag+ type from the device
+ */
 static VALUE dev_select(VALUE self, VALUE tag)
 {
   dev_info * dev;
@@ -44,6 +68,12 @@ static VALUE dev_select(VALUE self, VALUE tag)
   return Data_Wrap_Struct(cNfcISO14443A, 0, free, ti);
 }
 
+/*
+ * call-seq:
+ *  name
+ *
+ * Get the name of the tag reader
+ */
 static VALUE name(VALUE self)
 {
   dev_info * dev;
@@ -52,6 +82,12 @@ static VALUE name(VALUE self)
   return rb_str_new2(dev->acName);
 }
 
+/*
+ * call-seq:
+ *  deselect
+ *
+ * Deselect the current tag
+ */
 static VALUE dev_deselect(VALUE self)
 {
   dev_info * dev;

ext/nfc/nfc_iso14443a.c

@@ -2,6 +2,12 @@
 
 VALUE cNfcISO14443A;
 
+/*
+ * call-seq:
+ *  uiUidLen
+ *
+ * Get the uiUidLen
+ */
 static VALUE uiUidLen(VALUE self)
 {
   tag_info_iso14443a * tag;
@@ -10,6 +16,12 @@ static VALUE uiUidLen(VALUE self)
   return INT2NUM(tag->uiUidLen);
 }
 
+/*
+ * call-seq:
+ *  uiAtsLen
+ *
+ * Get the uiAtsLen
+ */
 static VALUE uiAtsLen(VALUE self)
 {
   tag_info_iso14443a * tag;
@@ -18,6 +30,12 @@ static VALUE uiAtsLen(VALUE self)
   return INT2NUM(tag->uiAtsLen);
 }
 
+/*
+ * call-seq:
+ *  abtUid
+ *
+ * Get the abtUid
+ */
 static VALUE abtUid(VALUE self)
 {
   tag_info_iso14443a * tag;
@@ -26,6 +44,12 @@ static VALUE abtUid(VALUE self)
   return rb_str_new(tag->abtUid, tag->uiUidLen);
 }
 
+/*
+ * call-seq:
+ *  abtAts
+ *
+ * Get the abtAts
+ */
 static VALUE abtAts(VALUE self)
 {
   tag_info_iso14443a * tag;
@@ -34,6 +58,12 @@ static VALUE abtAts(VALUE self)
   return rb_str_new(tag->abtAts, tag->uiAtsLen);
 }
 
+/*
+ * call-seq:
+ *  abtAtqa
+ *
+ * Get the abtAtqa
+ */
 static VALUE abtAtqa(VALUE self)
 {
   tag_info_iso14443a * tag;
@@ -42,6 +72,12 @@ static VALUE abtAtqa(VALUE self)
   return rb_str_new(tag->abtAtqa, 2);
 }
 
+/*
+ * call-seq:
+ *  btSak
+ *
+ * Get the btSak
+ */
 static VALUE btSak(VALUE self)
 {
   tag_info_iso14443a * tag;

lib/nfc.rb

@@ -4,68 +4,103 @@
 require 'nfc/device'
 require 'nfc/iso14443a'
 
+###
+# NFC is a class for dealing with Near Field Communication systems.  This
+# library will read RFID tags from an RFID reader.  You should start by reading
+# NFC#find
 class NFC
-  VERSION = '1.0.0'
+  VERSION = '2.0.0'
 
   include Singleton
 
+  ###
+  # Create a new NFC class.  This is private, do this instead:
+  #   NFC.instance
   def initialize
     @device = nil
     @mutex = Mutex.new
   end
 
+  ###
+  # Deactivate the detection field
   def deactivate_field
     device.configure Device::DCO_ACTIVATE_FIELD, 0
   end
 
+  ###
+  # Activate the detection field
   def activate_field
     device.configure Device::DCO_ACTIVATE_FIELD, 1
   end
 
+  ###
+  # Do CRC checks
   def crc= value
     device.configure Device::DCO_HANDLE_CRC, value ? 1 : 0
   end
 
+  ###
+  # Parity checks
   def parity= v
     device.configure Device::DCO_HANDLE_PARITY, v ? 1 : 0
   end
 
+  ###
+  # Get the device
   def device
-    @device ||= connect
+    @device ||= NFC::Device.connect
   end
 
+  ###
+  # Block until a passive tag is detected
   def infinite_list_passive= v
     device.configure Device::DCO_INFINITE_LIST_PASSIVE, v ? 1 : 0
   end
 
-  def poll_mifare
+  ###
+  # Select a tag
+  def select
     device.select Device::IM_ISO14443A_106
   end
+  alias :detect :select
 
+  ###
+  # Deselect a tag
   def deselect
     device.deselect
   end
 
+  # Read your tag and print the info.
+  #
+  #   p NFC.instance.find
+  #
+  # NFC#find will return immidiately, which means you should have a tag
+  # sitting on the reader when running it.  If you'd like it to block until
+  # it detects a tag, give find a block like so:
+  #
+  #   NFC.instance.find do |tag|
+  #     p tag
+  #   end
+  #
+  # You can even run in an infinite loop if you'd like to continually find
+  # tags:
+  #
+  #   loop do
+  #     NFC.instance.find do |tag|
+  #       p tag
+  #     end
+  #   end
   def find
     @mutex.lock
     deactivate_field
     self.infinite_list_passive = block_given?
     self.crc = true
     self.parity = true
     activate_field
-    tag = poll_mifare
+    tag = detect
     deselect
     @mutex.unlock
     yield tag if block_given?
     tag
   end
-
-  private
-  def connect
-    NFC::Device.connect
-  end
-
-  def disconnect
-    device.disconnect
-  end
 end

lib/nfc/iso14443a.rb

@@ -1,17 +1,25 @@
 class NFC
   class ISO14443A
+    ###
+    # Get the unique ID for this tag
     def uid
       abtUid.unpack 'C*'
     end
 
+    ###
+    # Get the ATS for this tag
     def ats
       abtAts.unpack 'C*'
     end
 
+    ###
+    # Get the atqa
     def atqa
       abtAtqa.unpack 'C*'
     end
 
+    ###
+    # Inspect this tag
     def inspect
       uid = sprintf((['%02x'] * uiUidLen).join('  '), *self.uid)