Improve documentation

6 files changed, 51 insertions, 6 deletions

diff --git a/docs/exceptions.rst b/docs/exceptions.rst
new file mode 100644
index 0000000..6916d50
--- /dev/null
+++ b/docs/exceptions.rst
@@ -0,0 +1,5 @@
+Exceptions
+==========
+
+.. automodule:: xdg.Exceptions
+   :members:
diff --git a/docs/index.rst b/docs/index.rst
index a00d740..2a797a3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,7 @@ Contents:
    icontheme
    mime
    recentfiles
+   exceptions
 
 Indices and tables
 ==================
diff --git a/setup.py b/setup.py
index 8ff5d79..8ff5d79 100644..100755
--- a/setup.py
+++ b/setup.py
diff --git a/xdg/DesktopEntry.py b/xdg/DesktopEntry.py
index 06c6c30..1387001 100644
--- a/xdg/DesktopEntry.py
+++ b/xdg/DesktopEntry.py
@@ -24,7 +24,7 @@ class DesktopEntry(IniFile):
     defaultGroup = 'Desktop Entry'
 
     def __init__(self, filename=None):
-        """Create a new DesktopEntry
+        """Create a new DesktopEntry.
         
         If filename exists, it will be parsed as a desktop entry file. If not,
         or if filename is None, a blank DesktopEntry is created.
@@ -39,7 +39,12 @@ class DesktopEntry(IniFile):
         return self.getName()
 
     def parse(self, file):
-        """Parse a desktop entry file."""
+        """Parse a desktop entry file.
+        
+        This can raise :class:`~xdg.Exceptions.ParsingError`,
+        :class:`~xdg.Exceptions.DuplicateGroupError` or
+        :class:`~xdg.Exceptions.DuplicateKeyError`.
+        """
         IniFile.parse(self, file, ["Desktop Entry", "KDE Desktop Entry"])
     
     def findTryExec(self):
@@ -150,10 +155,11 @@ class DesktopEntry(IniFile):
 
     # desktop entry edit stuff
     def new(self, filename):
-        """Make this instance into a new desktop entry.
+        """Make this instance into a new, blank desktop entry.
         
         If filename has a .desktop extension, Type is set to Application. If it
-        has a .directory extension, Type is Directory.
+        has a .directory extension, Type is Directory. Other extensions will
+        cause :class:`~xdg.Exceptions.ParsingError` to be raised.
         """
         if os.path.splitext(filename)[1] == ".desktop":
             type = "Application"
diff --git a/xdg/Exceptions.py b/xdg/Exceptions.py
index f7d08be..7096b61 100644
--- a/xdg/Exceptions.py
+++ b/xdg/Exceptions.py
@@ -5,6 +5,7 @@ Exception Classes for the xdg package
 debug = False
 
 class Error(Exception):
+    """Base class for exceptions defined here."""
     def __init__(self, msg):
         self.msg = msg
         Exception.__init__(self, msg)
@@ -12,40 +13,72 @@ class Error(Exception):
         return self.msg
 
 class ValidationError(Error):
+    """Raised when a file fails to validate.
+    
+    The filename is the .file attribute.
+    """
     def __init__(self, msg, file):
         self.msg = msg
         self.file = file
         Error.__init__(self, "ValidationError in file '%s': %s " % (file, msg))
 
 class ParsingError(Error):
+    """Raised when a file cannot be parsed.
+    
+    The filename is the .file attribute.
+    """
     def __init__(self, msg, file):
         self.msg = msg
         self.file = file
         Error.__init__(self, "ParsingError in file '%s', %s" % (file, msg))
 
 class NoKeyError(Error):
+    """Raised when trying to access a nonexistant key in an INI-style file.
+    
+    Attributes are .key, .group and .file.
+    """
     def __init__(self, key, group, file):
         Error.__init__(self, "No key '%s' in group %s of file %s" % (key, group, file))
         self.key = key
         self.group = group
+        self.file = file
 
 class DuplicateKeyError(Error):
+    """Raised when the same key occurs twice in an INI-style file.
+    
+    Attributes are .key, .group and .file.
+    """
     def __init__(self, key, group, file):
         Error.__init__(self, "Duplicate key '%s' in group %s of file %s" % (key, group, file))
         self.key = key
         self.group = group
+        self.file = file
 
 class NoGroupError(Error):
+    """Raised when trying to access a nonexistant group in an INI-style file.
+    
+    Attributes are .group and .file.
+    """
     def __init__(self, group, file):
         Error.__init__(self, "No group: %s in file %s" % (group, file))
         self.group = group
+        self.file = file
 
 class DuplicateGroupError(Error):
+    """Raised when the same key occurs twice in an INI-style file.
+    
+    Attributes are .group and .file.
+    """
     def __init__(self, group, file):
         Error.__init__(self, "Duplicate group: %s in file %s" % (group, file))
         self.group = group
+        self.file = file
 
 class NoThemeError(Error):
+    """Raised when trying to access a nonexistant icon theme.
+    
+    The name of the theme is the .theme attribute.
+    """
     def __init__(self, theme):
         Error.__init__(self, "No such icon-theme: %s" % theme)
         self.theme = theme
diff --git a/xdg/IniFile.py b/xdg/IniFile.py
index e507018..718589f 100644
--- a/xdg/IniFile.py
+++ b/xdg/IniFile.py
@@ -192,8 +192,8 @@ class IniFile:
 
     # start validation stuff
     def validate(self, report="All"):
-        """Validate the contents, raising ``ValidationError`` if there
-        is anything amiss.
+        """Validate the contents, raising :class:`~xdg.Exceptions.ValidationError`
+        if there is anything amiss.
         
         report can be 'All' / 'Warnings' / 'Errors'
         """