Add perl documentation. Probably not "perlish".

1 files changed, 114 insertions, 4 deletions

diff --git a/libvxi11client/perlbits/Client.pm b/libvxi11client/perlbits/Client.pm
index 39020a2..0b63212 100644
--- a/libvxi11client/perlbits/Client.pm
+++ b/libvxi11client/perlbits/Client.pm
@@ -33,9 +33,6 @@ our $VERSION = '0.01';
 require XSLoader;
 XSLoader::load('VXI11::Client', $VERSION);
 
-# Preloaded methods go here.
-
-
 sub vxi_enable_srq {
 	return vxi_enable_srq_long($_[0], 1, $_[1]);
 }
@@ -183,7 +180,6 @@ sub vxi_docmd {
 
 1;
 __END__
-# Below is stub documentation for your module. You'd better edit it!
 
 =head1 NAME
 
@@ -340,6 +336,120 @@ instruments. VXI-11 has mixed client and server roles (with interrupts the clien
 becomes the server). Starting the interrupt server creates an RPC server on the 
 client that the instruments can connect to.
 
+=head2 USAGE
+  
+INT vxi_startinterruptserver();
+	Start the local RPC service for the instrument to connect to and deliver
+	interrupt/service requests to.
+	Make sure you have portmapper or rpcbind running and you aren't blocking
+	the ports it allocates.
+
+INT vxi_stopinterruptserver();
+	Shutdown the local RPC server.
+
+INT INST = vxi_open( address => STRING, [device => STRING] );
+	Open a link to an instrument. Use the returned instance to call 
+	the object methods below.
+
+INT INST->vxi_close();
+	Destroy the link to the insturment and destroy the local RPC client.
+	You must not use an instance created with vxi_open(); after calling this.
+
+INT INST->vxi_lock([waitforlock => 'false'])
+	Lock the instrument. You can tell the instrument to try to wait for 
+	the lock to become free and lock it via waitforlock,
+
+INT INST->vxi_unlock();
+	Unlock the instrument. Only makes sense if you are holding the lock.
+              
+INT INST->vxi_write(STRING data, [ len => -1,
+                		   waitforlock => 0,
+                                   end => 1 ]);
+	Write data to the instrument. If the data is a terminated string you can 
+	pass -1 as the length to have it calculated for you. If the data is not 
+	terminated or for some reason you only want to write part of it you need
+	to provide a length. You can wait for the lock to be freed by via waitforlock.  
+	       
+(INT bytes, STRING string, INT reason) INST->vxi_read([ bufferlen => 1024,
+                     			    waitforlock => 0,
+                     			    termchrset => 0,
+                     			    termchr => 0,
+                     			    autochomp => 1]);
+
+	Read some data from the instrument. The default parameters should be fine
+	for most cases. If you need to read more than 1024 bytes you should pass 
+	in the required buffer size via bufferlen. This function will not read more 
+	than the buffer size. The number of bytes returned is what the instrument sent
+	not what was copied into the buffer. So if the number of bytes returned is
+	larger than bufferlen the data is truncated. If autochomp is set the newline
+	from the returned data will be automatically removed.
+
+(INT ret, STRING dataout, INT dataoutlen) =  vxi_docmd (INT cmd, [ datain => "",
+             						  	   datainlen => -1,
+            						  	   dataoutbufferlen => 256,
+             						           waitforlock => 0,
+             						           autochomp => 1]);
+
+	Send a command to the instrument possibly with some data. The rules for write apply
+	to datain and the rules for read apply for dataout.
+
+INT INST->vxi_abort();
+	Abort an in-progress operation.	
+
+INT vxi_readstatusbyte([ waitforlock => 0 ]);
+
+	Read the instruments status byte.
+
+INT INST->vxi_create_intr_chan();   
+
+	Creates an interrupt channel from the instrument to this client.
+	This must be called after vxi_startinterruptserver.
+
+INT INST->vxi_enable_srq(STRING handle);
+
+	Tell the instrument to fire interrupts/service requests to the 
+	interrupt channel. Must be called after vxi_create_intr_chan().
+	You should give a unique channel handle for each instrument as
+	you will need this to work out which device set an interrupt/service 
+	request. 
+
+INT INST->vxi_disable_srq();
+
+	Tell the instrument that you don't want it to send interrupts/
+	service requests anymore. This does not destroy the interrupt 
+	channel.
+
+INT INST->vxi_destroy_intr_chan();
+
+	Tell the instrument to disconnect from the interrupt service that
+	is running locally. This does not shut down the interrupt service.
+
+STRING vxi_wait_for_interrupt([INT timeout -1 : 0 : n])
+
+	Waits for an interrupt/service request to be received from a connected 
+	instrument. When an interrupt is caught the handle of the interrupt will
+	be returned. If no interrupt is caught undef will be returned.
+	You can pass a timeout in ms (the default is 250ms), or 0 to never block
+	and only return interrupts that have already happened or -1 to block until
+	an interrupt is caught (could block forever!).
+
+INT INST->vxi_remote([waitforlock => 0]);      
+
+	Lock out the instrument's display.
+
+INT INST->vxi_local([waitforlock => 0]);
+
+	Unlock the instrument's display.
+	
+INT INST->vxi_clear([waitforlock => 0]);
+
+	Clear the instruments's display.
+
+INT INST->vxi_trigger([waitforlock => 0]);
+
+	Trigger the instrument.
+
+
 Return codes work like this;
 1   - is a success
 0   - means the request failed locally, the state inside the client is