From 12d473ced6ac24e00e8f080513ca439e6b459e6a Mon Sep 17 00:00:00 2001
From: Stein Magnus Jodal <stein.magnus@jodal.no>
Date: Sun, 29 Dec 2013 15:38:20 +0100
Subject: [PATCH] zeroconf: Make public API with docs

---
 docs/api/index.rst             |  1 +
 docs/api/zeroconf.rst          | 11 +++++++++++
 mopidy/frontends/http/actor.py |  3 +--
 mopidy/frontends/mpd/actor.py  |  3 ++-
 mopidy/{utils => }/zeroconf.py | 27 +++++++++++++++++++++++++--
 5 files changed, 40 insertions(+), 5 deletions(-)
 create mode 100644 docs/api/zeroconf.rst
 rename mopidy/{utils => }/zeroconf.py (76%)

diff --git a/docs/api/index.rst b/docs/api/index.rst
index f58552b7..a79f2bae 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -16,4 +16,5 @@ API reference
     commands
     ext
     config
+    zeroconf
     http
diff --git a/docs/api/zeroconf.rst b/docs/api/zeroconf.rst
new file mode 100644
index 00000000..7cdd93f0
--- /dev/null
+++ b/docs/api/zeroconf.rst
@@ -0,0 +1,11 @@
+.. _zeroconf-api:
+
+************
+Zeroconf API
+************
+
+.. module:: mopidy.zeroconf
+    :synopsis: Helper for publishing of services on Zeroconf
+
+.. autoclass:: Zeroconf
+    :members:
diff --git a/mopidy/frontends/http/actor.py b/mopidy/frontends/http/actor.py
index 4e3493d4..5aef3506 100644
--- a/mopidy/frontends/http/actor.py
+++ b/mopidy/frontends/http/actor.py
@@ -9,9 +9,8 @@ import pykka
 from ws4py.messaging import TextMessage
 from ws4py.server.cherrypyserver import WebSocketPlugin, WebSocketTool
 
-from mopidy import models
+from mopidy import models, zeroconf
 from mopidy.core import CoreListener
-from mopidy.utils import zeroconf
 from . import ws
 
 
diff --git a/mopidy/frontends/mpd/actor.py b/mopidy/frontends/mpd/actor.py
index 9df7ba07..fb063f6c 100644
--- a/mopidy/frontends/mpd/actor.py
+++ b/mopidy/frontends/mpd/actor.py
@@ -5,9 +5,10 @@ import sys
 
 import pykka
 
+from mopidy import zeroconf
 from mopidy.core import CoreListener
 from mopidy.frontends.mpd import session
-from mopidy.utils import encoding, network, process, zeroconf
+from mopidy.utils import encoding, network, process
 
 logger = logging.getLogger('mopidy.frontends.mpd')
 
diff --git a/mopidy/utils/zeroconf.py b/mopidy/zeroconf.py
similarity index 76%
rename from mopidy/utils/zeroconf.py
rename to mopidy/zeroconf.py
index acd25ef1..671bebc7 100644
--- a/mopidy/utils/zeroconf.py
+++ b/mopidy/zeroconf.py
@@ -4,7 +4,7 @@ import logging
 import socket
 import string
 
-logger = logging.getLogger('mopidy.utils.zeroconf')
+logger = logging.getLogger('mopidy.zeroconf')
 
 try:
     import dbus
@@ -25,7 +25,20 @@ def _convert_text_to_dbus_bytes(text):
 
 
 class Zeroconf(object):
-    """Publish a network service with Zeroconf using Avahi."""
+    """Publish a network service with Zeroconf.
+
+    Currently, this only works on Linux using Avahi via D-Bus.
+
+    :param str name: human readable name of the service, e.g. 'MPD on neptune'
+    :param int port: TCP port of the service, e.g. 6600
+    :param str stype: service type, e.g. '_mpd._tcp'
+    :param str domain: local network domain name, defaults to ''
+    :param str host: interface to advertise the service on, defaults to all
+        interfaces
+    :param text: extra information depending on ``stype``, defaults to empty
+        list
+    :type text: list of str
+    """
 
     def __init__(self, name, port, stype=None, domain=None,
                  host=None, text=None):
@@ -44,6 +57,11 @@ class Zeroconf(object):
             hostname=self.host or socket.getfqdn(), port=self.port)
 
     def publish(self):
+        """Publish the service.
+
+        Call when your service starts.
+        """
+
         if _is_loopback_address(self.host):
             logger.info(
                 'Zeroconf publish on loopback interface is not supported.')
@@ -83,6 +101,11 @@ class Zeroconf(object):
             return False
 
     def unpublish(self):
+        """Unpublish the service.
+
+        Call when your service shuts down.
+        """
+
         if self.group:
             try:
                 self.group.Reset()