From de6d4f7e7bdb78e5cb443a2e327265b52cde0d44 Mon Sep 17 00:00:00 2001
From: drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Tue, 16 Aug 2011 00:34:51 +0000
Subject: * ext/dl:  Add documentation.  Patch by Vincent Batts.  [Ruby 1.9 -
 Bug #5192]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32982 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ext/dl/lib/dl/callback.rb | 26 +++++++++++++++++++++-----
 ext/dl/lib/dl/import.rb   | 16 ++++++++++++++++
 ext/dl/lib/dl/types.rb    | 31 +++++++++++++++++++++++++++++--
 3 files changed, 66 insertions(+), 7 deletions(-)

(limited to 'ext/dl/lib/dl')

diff --git a/ext/dl/lib/dl/callback.rb b/ext/dl/lib/dl/callback.rb
index 0863c70d4d..1722d3c6b9 100644
--- a/ext/dl/lib/dl/callback.rb
+++ b/ext/dl/lib/dl/callback.rb
@@ -2,13 +2,29 @@ require 'dl'
 require 'thread'
 
 module DL
-  SEM = Mutex.new
+	# The mutual exclusion (Mutex) semaphore for the DL module
+  SEM = Mutex.new # :nodoc:
 
   if DL.fiddle?
-    CdeclCallbackProcs = {}
-    CdeclCallbackAddrs = {}
-    StdcallCallbackProcs = {}
-    StdcallCallbackAddrs = {}
+    # A Hash of callback Procs
+    #
+    # Uses Fiddle
+    CdeclCallbackProcs = {} # :nodoc:
+
+    # A Hash of the addresses of callback Proc
+    #
+    # Uses Fiddle
+    CdeclCallbackAddrs = {} # :nodoc:
+
+    # A Hash of Stdcall callback Procs
+    #
+    # Uses Fiddle on win32
+    StdcallCallbackProcs = {} # :nodoc:
+
+    # A Hash of the addresses of Stdcall callback Procs
+    #
+    # Uses Fiddle on win32
+    StdcallCallbackAddrs = {} # :nodoc:
   end
 
   def set_callback_internal(proc_entry, addr_entry, argc, ty, abi = nil, &cbp)
diff --git a/ext/dl/lib/dl/import.rb b/ext/dl/lib/dl/import.rb
index f22a53aa84..eec65cdfd6 100644
--- a/ext/dl/lib/dl/import.rb
+++ b/ext/dl/lib/dl/import.rb
@@ -31,6 +31,22 @@ module DL
     end
   end
 
+  # DL::Importer includes the means to dynamically load libraries and build
+  # modules around them including calling extern functions within the C
+  # library that has been loaded.
+  #
+  # == Example
+  #
+  #   require 'dl'
+  #   require 'dl/import'
+  #
+  #   module LibSum
+  #   	extend DL::Importer
+  #   	dlload './libsum.so'
+  #   	extern 'double sum(double*, int)'
+  #   	extern 'double split(double)'
+  #   end
+	#
   module Importer
     include DL
     include CParser
diff --git a/ext/dl/lib/dl/types.rb b/ext/dl/lib/dl/types.rb
index b85ac890cd..c79f74f95c 100644
--- a/ext/dl/lib/dl/types.rb
+++ b/ext/dl/lib/dl/types.rb
@@ -1,6 +1,29 @@
 module DL
+  # Adds Windows type aliases to the including class for use with
+  # DL::Importer.
+  #
+  # The aliases added are:
+  # * ATOM
+  # * BOOL
+  # * BYTE
+  # * DWORD
+  # * HANDLE
+  # * HDC
+  # * HINSTANCE
+  # * HWND
+  # * LPCSTR
+  # * LPSTR
+  # * PBYTE
+  # * PDWORD
+  # * PHANDLE
+  # * PVOID
+  # * PWORD
+  # * UCHAR
+  # * UINT
+  # * ULONG
+  # * WORD
   module Win32Types
-    def included(m)
+    def included(m) # :nodoc:
       m.module_eval{
         typealias "DWORD", "unsigned long"
         typealias "PDWORD", "unsigned long *"
@@ -26,8 +49,12 @@ module DL
     module_function :included
   end
 
+  # Adds basic type aliases to the including class for use with DL::Importer.
+  #
+  # The aliases added are +uint+ and +u_int+ (<tt>unsigned int</tt>) and
+  # +ulong+ and +u_long+ (<tt>unsigned long</tt>)
   module BasicTypes
-    def included(m)
+    def included(m) # :nodoc:
       m.module_eval{
         typealias "uint", "unsigned int"
         typealias "u_int", "unsigned int"
-- 
cgit v1.2.3