Index: trunk/python/pyregfi/__init__.py
===================================================================
--- trunk/python/pyregfi/__init__.py	(revision 256)
+++ trunk/python/pyregfi/__init__.py	(revision 257)
@@ -11,11 +11,9 @@
 #
 # The library operates on registry hives, each of which is contained within a
-# single file.  To get started, one must first open the registry hive file with
-# the open() or file() Python built-in functions (or equivalent) and then pass
-# the resulting file object to pyregfi. For example:
+# single file.  The quickest way to get started, is to use the @ref openHive() 
+# function to obtain a Hive object.  For example:
 # @code
 # >>> import pyregfi
-# >>> fh = open('/mnt/win/c/WINDOWS/system32/config/system', 'rb')
-# >>> myHive = pyregfi.Hive(fh)
+# >>> myHive = pyregfi.openHive('/mnt/win/c/WINDOWS/system32/config/system')
 # @endcode
 #
@@ -300,5 +298,5 @@
 # 
 class Security(_StructureWrapper):
-    ## Number of keys referencing this SK record 
+    ## Number of registry Keys referencing this SK record
     ref_count = 1
 
@@ -306,5 +304,5 @@
     offset = 0xCAFEBABE
 
-    ## The @ref SecurityDescriptor for this SK record
+    ## The @ref winsec.SecurityDescriptor for this SK record
     descriptor = object()
 
@@ -314,5 +312,5 @@
         self.descriptor = winsec.SecurityDescriptor(base.contents.sec_desc.contents)
 
-    ## Loads the "previous" Security record in the hive
+    ## Loads the "next" Security record in the hive
     #
     # @note
@@ -337,4 +335,5 @@
 ## Abstract class for ValueList and SubkeyList
 class _GenericList(object):
+    # XXX: consider implementing keys(), values(), items() and other dictionary methods
     _hive = None
     _key_base = None
@@ -373,7 +372,19 @@
     ## Retrieves a list element by name
     #
+    # @param name The name of the subkey or value desired.  
+    #             This is case-sensitive.
+    #
+    # @note The registry format does inherently prevent multiple
+    #       subkeys or values from having the same name.  
+    #       This interface simply returns the first match.  
+    #       Lookups using this method could also fail due to incorrectly
+    #       encoded strings.
+    #       To identify any duplicates, use the iterator interface to 
+    #       check every list element.
+    #
     # @return the first element whose name matches, or None if the element
     #         could not be found
     def __getitem__(self, name):
+        # XXX: Consider interpreting integer names as offsets in the underlying list
         index = ctypes.c_uint32()
         if isinstance(name, str):
@@ -391,4 +402,8 @@
         raise KeyError('')
 
+
+    ## Fetches the requested element by name, or the default value if the lookup
+    #  fails.
+    # 
     def get(self, name, default):
         try:
@@ -426,7 +441,7 @@
 # @endcode
 #
-# @note SubkeyLists should never be accessed directly and only exist
-#       in association with a parent Key object.  Do not retain references to 
-#       SubkeyLists.  Instead, access them via their parent Key at all times.
+# You may also request the len() of a subkeys list. 
+# However keys(), values(), items() and similar methods are not currently 
+# implemented.
 class SubkeyList(_GenericList):
     _fetch_num = regfi.regfi_fetch_num_subkeys
@@ -447,7 +462,7 @@
 # @endcode
 #
-# @note ValueLists should never be accessed directly and only exist
-#       in association with a parent Key object.  Do not retain references to 
-#       ValueLists.  Instead, access them via their parent Key at all times.
+# You may also request the len() of a values list. 
+# However keys(), values(), items() and similar methods are not currently 
+# implemented.
 class ValueList(_GenericList):
     _fetch_num = regfi.regfi_fetch_num_values
@@ -460,8 +475,8 @@
 # access to their subkeys, values, and other metadata.
 #
-# @note Value instances may provide access to more than the attributes
+# @note Key instances may provide access to more attributes than are
 #       documented here.  However, undocumented attributes may change over time
 #       and are not officially supported.  If you need access to an attribute 
-#       not shown here, see pyregfi.structures.
+#       not shown here, see @ref pyregfi.structures.
 class Key(_StructureWrapper):
     ## A @ref ValueList object representing the list of Values 
@@ -558,4 +573,8 @@
         return None
 
+
+    ## Checks to see if this Key is the root of its Hive
+    #
+    #  @return True if it is, False otherwise
     def is_root(self):
         return (self._hive.root == self)
@@ -567,8 +586,8 @@
 # access to their associated data.
 #
-# @note Value instances may provide access to more than the attributes
+# @note Value instances may provide access to more attributes than are
 #       documented here.  However, undocumented attributes may change over time
 #       and are not officially supported.  If you need access to an attribute
-#       not shown here, see pyregfi.structures.
+#       not shown here, see @ref pyregfi.structures.
 class Value(_StructureWrapper):
     ## The raw Value name as an uninterpreted bytearray
Index: trunk/python/pyregfi/winsec.py
===================================================================
--- trunk/python/pyregfi/winsec.py	(revision 256)
+++ trunk/python/pyregfi/winsec.py	(revision 257)
@@ -97,5 +97,6 @@
 
 ## Represents a Microsoft access control entry, which are elements of access
-#  control lists
+#  control lists.  For more information, see: 
+#    http://msdn.microsoft.com/en-us/library/aa374868%28v=vs.85%29.aspx
 #
 #  @note
@@ -136,4 +137,8 @@
 
 
+## A Microsoft security descriptor
+# For more information, see:
+#   http://msdn.microsoft.com/en-us/library/aa379563%28v=vs.85%29.aspx
+#
 class SecurityDescriptor(object):
     ## The security descriptor's owner SID, as a string
@@ -143,10 +148,12 @@
     group = "S-1-2-..."
 
-    ## A list of @ref ACE objects which represents the System ACL
-    # May be None if a sacl isn't defined
+    ## The system access control list represented as a list of @ref ACE objects.
+    # 
+    # Is set to None if a sacl isn't defined
     sacl = []
 
-    ## A list of @ref ACE objects which represents the User ACL
-    # May be None if a dacl isn't defined
+    ## The discretionary access control list represented as a list of @ref ACE objects
+    #
+    # Is set to None if a dacl isn't defined
     dacl = []
 
@@ -160,5 +167,4 @@
         libc.free(c_str)
 
-        # XXX: add checks for NULL pointers
         self.sacl = None
         if sec_desc.sacl:
