Update documentation for Browser class.

src/include/qmdnsengine/browser.h

@@ -40,7 +40,34 @@ class Service;
 class QMDNSENGINE_EXPORT BrowserPrivate;
 
 /**
- * @brief Find local services
+ * @brief %Browser for local services
+ *
+ * This class provides a simple way to discover services on the local network.
+ * A cache may be provided in the constructor to store records for future
+ * queries.
+ *
+ * To browse for services of any type:
+ *
+ * @code
+ * QMdnsEngine::Browser browser(&server, QMdnsEngine::MdnsBrowseType);
+ * @endcode
+ *
+ * To browse for services of a specific type:
+ *
+ * @code
+ * QMdnsEngine::Browser browser(&server, "_http._tcp.local.");
+ * @endcode
+ *
+ * When a service is found, the serviceAdded() signal is emitted:
+ *
+ * @code
+ * connect(&browser, &QMdnsEngine::Browser::serviceAdded, [](const QMdnsEngine::Service &service) {
+ *     qDebug() << "Service added:" << service.name();
+ * });
+ * @endcode
+ *
+ * The serviceUpdated() and serviceRemoved() signals are emitted when services
+ * are updated (their properties change) or are removed, respectively.
  */
 class QMDNSENGINE_EXPORT Browser : public QObject
 {
@@ -61,6 +88,10 @@ Q_SIGNALS:
 
     /**
      * @brief Indicate that a new service has been added
+     *
+     * This signal is emitted when the PTR and SRV records for a service are
+     * received. If TXT records are received later, the serviceUpdated()
+     * signal will be emitted.
      */
     void serviceAdded(const Service &service);
 
@@ -68,12 +99,16 @@ Q_SIGNALS:
      * @brief Indicate that the specified service was updated
      *
      * This signal is emitted when the SRV record for a service (identified by
-     * its name and type) has changed.
+     * its name and type) or a TXT record has changed.
      */
     void serviceUpdated(const Service &service);
 
     /**
      * @brief Indicate that the specified service was removed
+     *
+     * This signal is emitted when an essential record (PTR or SRV) is
+     * expiring from the cache. This will also occur when an updated PTR or
+     * SRV record is received with a TTL of 0.
      */
     void serviceRemoved(const Service &service);
 

src/src/browser.cpp

@@ -43,7 +43,6 @@ BrowserPrivate::BrowserPrivate(Browser *browser, AbstractServer *server, const Q
       cache(existingCache ? existingCache : new Cache(this))
 {
     connect(server, &AbstractServer::messageReceived, this, &BrowserPrivate::onMessageReceived);
-
     connect(cache, &Cache::shouldQuery, this, &BrowserPrivate::onShouldQuery);
     connect(cache, &Cache::recordExpired, this, &BrowserPrivate::onRecordExpired);
     connect(&queryTimer, &QTimer::timeout, this, &BrowserPrivate::onQueryTimeout);
@@ -52,6 +51,7 @@ BrowserPrivate::BrowserPrivate(Browser *browser, AbstractServer *server, const Q
     queryTimer.setSingleShot(true);
     serviceTimer.setSingleShot(true);
 
+    // Immediately begin browsing for services
     onQueryTimeout();
 }
 
@@ -59,16 +59,19 @@ BrowserPrivate::BrowserPrivate(Browser *browser, AbstractServer *server, const Q
 
 bool BrowserPrivate::updateService(const QByteArray &fqName)
 {
-    QByteArray serviceName = fqName.left(fqName.indexOf('.'));
-    QByteArray serviceType = fqName.mid(fqName.indexOf('.') + 1);
+    // Split the FQDN into service name and type
+    int index = fqName.indexOf('.');
+    QByteArray serviceName = fqName.left(index);
+    QByteArray serviceType = fqName.mid(index + 1);
 
     // Immediately return if a PTR record does not exist
-    Record ptrRecord, srvRecord;
+    Record ptrRecord;
     if (!cache->lookupRecord(serviceType, PTR, ptrRecord)) {
         return false;
     }
 
-    // If a SRV record is missing, query for it
+    // If a SRV record is missing, query for it (by returning true)
+    Record srvRecord;
     if (!cache->lookupRecord(fqName, SRV, srvRecord)) {
         return true;
     }