updated docs and doc strings

docs/api/utils/index.rst

@@ -9,6 +9,9 @@ maestral.utils
    utils.autostart <autostart>
    utils.housekeeping <housekeeping>
    utils.notify <notify>
+   utils.notify_base <notify_base>
+   utils.notify_macos <notify_macos>
+   utils.notify_linux <notify_linux>
    utils.path <path>
    utils.serializer <serializer>
    utils.updates <updates>

docs/api/utils/notify_base.rst

@@ -0,0 +1,7 @@
+Desktop notifications base
+==========================
+
+.. automodule:: utils.notify_base
+   :members:
+   :show-inheritance:
+   

docs/api/utils/notify_linux.rst

@@ -0,0 +1,7 @@
+Desktop notifications
+=====================
+
+.. automodule:: utils.notify_linux
+   :members:
+   :show-inheritance:
+   

docs/api/utils/notify_macos.rst

@@ -0,0 +1,7 @@
+Desktop notifications
+=====================
+
+.. automodule:: utils.notify_macos
+   :members:
+   :show-inheritance:
+   

docs/api/utils/updates.rst

@@ -1,7 +0,0 @@
-
-Update checks
-=============
-
-.. automodule:: utils.updates
-   :members:
-   :show-inheritance:

maestral/daemon.py

@@ -72,7 +72,14 @@ def freeze_support() -> None:
 
 
 class Stop(enum.Enum):
-    """Enumeration of daemon exit results."""
+    """
+    Enumeration of daemon exit results.
+    
+    :cvar Ok: Daemon quit successfully.
+    :cvar Killed: Daemon process was killed.
+    :cvar NotRunning: Daemon was not running.
+    :cvar Failed: Could not shut down daemon.
+    """
     Ok = 0
     Killed = 1
     NotRunning = 2
@@ -80,7 +87,13 @@ class Stop(enum.Enum):
 
 
 class Start(enum.Enum):
-    """Enumeration of daemon start results."""
+    """
+    Enumeration of daemon start results.
+
+    :cvar Ok: Daemon started successfully.
+    :cvar AlreadyRunning: Daemon was already running.
+    :cvar Failed: Could not start daemon.
+    """
     Ok = 0
     AlreadyRunning = 1
     Failed = 2

maestral/sync.py

@@ -403,7 +403,7 @@ class PersistentStateMutableSet(abc.MutableSet):
 class SyncEvent(Base):  # type: ignore
     """
     Represents a file or folder change in the sync queue. This is used to abstract the
-    :class:`watchdog.events.FileSystemEvent`s created for local changes and the
+    :class:`watchdog.events.FileSystemEvent` created for local changes and the
     :class:`dropbox.files.Metadata` created for remote changes. All arguments are used to
     construct instance attributes and some attributes may not be set for all event types.
     Note that some instance attributes depend on the state of the Maestral instance, e.g.,
@@ -448,7 +448,7 @@ class SyncEvent(Base):  # type: ignore
     :param completed: File size in bytes which has already been uploaded or downloaded.
         Always zero for folders.
 
-    :attr change_time_or_sync_time: Change time when available, otherwise sync time. This
+    :ivar change_time_or_sync_time: Change time when available, otherwise sync time. This
         can be used for sorting or user information purposes.
     """
 

maestral/utils/notify.py

@@ -36,8 +36,8 @@ class DesktopNotifier:
     depending on the platform version and available services. The Dbus backend requires
     a running asyncio loop. The Cocoa implementations will dispatch notifications without
     an event loop but require a running CFRunLoop *in the main thread* to react to user
-    interactions with the notification. Packages such as :package:`rubicon.objc` can be
-    used to integrate asyncio with a CFRunLoop.
+    interactions with the notification. Packages such as :mod:`rubicon.objc` can be used
+    to integrate asyncio with a CFRunLoop.
 
     :param app_name: Name of app which sends notifications.
     :param app_id: Bundle identifier of the app. This is typically a reverse domain name

maestral/utils/notify_base.py

@@ -4,6 +4,8 @@
 
 (c) Sam Schott; This work is licensed under the MIT licence.
 
+This module defines base classes for desktop notifications. 
+
 """
 
 # system imports
@@ -13,7 +15,12 @@ from typing import Optional, Dict, Callable, Union
 
 class NotificationLevel(Enum):
     """
-    Enumeration of notification levels.
+    Enumeration of notification levels. The interpretation and visuals will depend
+    on the platform.
+    
+    :cvar Critical: For critical errors.
+    :cvar Normal: Default platform notification level.
+    :cvar Low: Low priority notification.
     """
     Critical = 'critical'
     Normal = 'normal'