From 26db1e52df2773cc59be07abcc9f19a1cb73911b Mon Sep 17 00:00:00 2001
From: Evan Broder <broder@mit.edu>
Date: Mon, 11 Aug 2008 17:07:52 -0700
Subject: [PATCH] Lots of docstrings!

---
 routefs/__init__.py |   55 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 mode change 100755 => 100644 routefs/__init__.py

diff --git a/routefs/__init__.py b/routefs/__init__.py
old mode 100755
new mode 100644
index 8519a1a..88b4f5c
--- a/routefs/__init__.py
+++ b/routefs/__init__.py
@@ -1,3 +1,16 @@
+"""
+RouteFS is a base class for developing read-only FUSE filesystems that
+lets you focus on the directory tree instead of the system calls.
+
+RouteFS uses the Routes library developed for Pylons. URLs were
+inspired by filesystems, and now you can have filesystems inspired by
+URLs.
+
+When developing a descendent of RouteFS, any methods defined in that
+class are considered "controllers", and receive any other parameters
+specified by the URL as keyword arguments.
+"""
+
 import fuse
 import routes
 import errno
@@ -6,6 +19,10 @@ import stat
 fuse.fuse_python_api = (0, 2)
 
 class RouteStat(fuse.Stat):
+    """
+    RouteStat is a descendent of fuse.Stat, defined to make sure that
+    all of the necessary attributes are always defined
+    """
     def __init__(self):
         self.st_mode = 0
         self.st_ino = 0
@@ -19,6 +36,14 @@ class RouteStat(fuse.Stat):
         self.st_ctime = 0
 
 class RouteMeta(type):
+    """
+    Metaclass to calculate controller methods
+    
+    Routes needs to be pre-seeded with a list of "controllers". For
+    all descendents of RouteFS, the list of controllers is defined to
+    be any non-private methods of the class that were not in the
+    RouteFS class.
+    """
     def __init__(cls, classname, bases, dict_):
         super(RouteMeta, cls).__init__(classname, bases, dict_)
         if bases != (fuse.Fuse,):
@@ -27,6 +52,9 @@ class RouteMeta(type):
                                  if not func.startswith('_')])
 
 class RouteFS(fuse.Fuse):
+    """
+    RouteFS: Web 2.0 for filesystems
+    """
     __metaclass__ = RouteMeta
     def __init__(self, *args, **kwargs):
         super(RouteFS, self).__init__(*args, **kwargs)
@@ -35,6 +63,10 @@ class RouteFS(fuse.Fuse):
         self.map.create_regs(self.controller_list)
         
     def make_map(self):
+        """
+        This method should be overridden by descendents of RouteFS to
+        define the routing for the filesystem
+        """
         m = routes.Mapper()
         
         m.connect(':controller')
@@ -46,6 +78,9 @@ class RouteFS(fuse.Fuse):
         cls.controller_list = lst
     
     def _get_file(self, path):
+        """
+        Find the filesystem entry object for a given path
+        """
         match = self.map.match(path)
         if match is None:
             return
@@ -54,6 +89,10 @@ class RouteFS(fuse.Fuse):
         return result
     
     def readdir(self, path, offset):
+        """
+        If the path referred to is a directory, return the elements of
+        that diectory
+        """
         obj = self._get_file(path)
         if type(obj) is not Directory:
             return
@@ -62,6 +101,12 @@ class RouteFS(fuse.Fuse):
                 yield fuse.Direntry(str(member))
     
     def getattr(self, path):
+        """
+        Return the stat information for a path
+        
+        The stat information for a directory, symlink, or file is
+        predetermined based on which it is.
+        """
         obj = self._get_file(path)
         if obj is None:
             return -errno.ENOENT
@@ -82,6 +127,10 @@ class RouteFS(fuse.Fuse):
         return st
     
     def read(self, path, length, offset):
+        """
+        If the path specified is a file, return the requested portion
+        of the file
+        """
         obj = self._get_file(path)
         if obj is None:
             return -errno.ENOENT
@@ -91,6 +140,9 @@ class RouteFS(fuse.Fuse):
             return obj[offset:offset + length]
     
     def readlink(self, path):
+        """
+        If the path specified is a symlink, return the target
+        """
         obj = self._get_file(path)
         if type(obj) is not Symlink:
             return -errno.EINVAL
@@ -111,6 +163,9 @@ class Symlink(str):
     pass
 
 def main(cls):
+    """
+    A convenience function for initializing a RouteFS filesystem
+    """
     server = cls(version="%prog " + fuse.__version__,
                  usage=fuse.Fuse.fusage,
                  dash_s_do='setsingle')
-- 
1.7.9.5