[ozone] adding comments/examples for path functions

desktop/core/src/desktop/lib/fs/ozone/__init__.py

@@ -34,6 +34,7 @@ def is_root(uri):
 def normpath(path):
   """
   Return normalized path but ignore leading OFS_ROOT prefix if it exists
+  normpath('ofs://vol1/') == 'ofs://vol1'
   """
   if path.lower().startswith(OFS_ROOT):
     if is_root(path):
@@ -79,25 +80,31 @@ def _append_separator(path):
 
 def parse_uri(uri):
   """
-  Returns tuple (volume_name, bucket_name, key_name).
+  Returns tuple (volume_name, key_name, key_basename).
   Raises ValueError if invalid OFS URI is passed.
+  
+  ofs://volume1/bucket1/key1/key2 -> 
+  group1 -> volume1
+  group2 -> /bucket1/key1/key2
+  group3 -> bucket1/key1/key2
+  group4 -> key2
   """
   match = OFS_PATH_RE.match(uri)
   if not match:
     raise ValueError("Invalid OFS URI: %s" % uri)
-  bucket = match.group(3) or ''
-  basename = match.group(4) or ''
-  return match.group(1), bucket, basename
+  key_name = match.group(3) or ''
+  key_basename = match.group(4) or ''
+  return match.group(1), key_name, key_basename
 
 
 def parent_path(path):
   parent_dir = _append_separator(path)
   if not is_root(parent_dir):
-    volume_name, bucket_name, basename = parse_uri(path)
-    if not basename:  # bucket is top-level so return root
+    volume_name, key_name, key_basename = parse_uri(path)
+    if not key_basename:  # volume is top-level so return root
       parent_dir = OFS_ROOT
     else:
       volume_path = '%s%s' % (OFS_ROOT, volume_name)
-      bucket_path = '/'.join(bucket_name.split('/')[:-1])
-      parent_dir = abspath(volume_path, bucket_path)
+      key_path = '/'.join(key_name.split('/')[:-1])
+      parent_dir = abspath(volume_path, key_path)
   return parent_dir