* api documentation

* void addSource(DataSource* source): allows adding of DataSources directly; useful for more complex engines where setData would be inneficient and clumsy or just not powerful enough

svn path=/trunk/KDE/kdebase/workspace/plasma/lib/; revision=667584

dataengine.cpp

@@ -49,9 +49,9 @@ class DataEngine::Private
                      << ": could not find DataSource " << sourceName
                      << ", creating" << endl;
             DataSource* s = new DataSource(engine);
-            emit engine->newDataSource(sourceName);
             s->setName(sourceName);
             sources.insert(sourceName, s);
+            emit engine->newDataSource(sourceName);
             return s;
         }
 
@@ -125,6 +125,18 @@ void DataEngine::setData(const QString& source, const QString& key, const QVaria
     d->queueUpdate();
 }
 
+void DataEngine::addSource(DataSource* source)
+{
+    DataSource::Dict::const_iterator it = d->sources.find(source->name());
+    if (it != d->sources.constEnd()) {
+        kDebug() << "source named \"" << source->name() << "\" already exists." << endl;
+        return;
+    }
+
+    d->sources.insert(source->name(), source);
+    emit newDataSource(source->name());
+}
+
 /*
 Plasma::DataSource* DataEngine::createDataSource(const QString& source, const QString& domain)
 {

dataengine.h

@@ -29,6 +29,22 @@
 namespace Plasma
 {
 
+class DataSource;
+
+/**
+ * @class DataEngine
+ * @brief Data provider for plasmoids (Plasma plugins)
+ *
+ * This is the base class for DataEngines, which provide access to bodies of
+ * data via a common and consistent interface. The common use of a DataEngine
+ * is to provide data to a widget for display. This allows a user interface
+ * element to show all sorts of data: as long as there is a DataEngine, the
+ * data is retrievable.
+ *
+ * DataEngines are loaded as plugins on demand and provide one more data
+ * sources which are identified by name. For instance, a network DataEngine
+ * might provide a data source for each network interface.
+ **/
 class PLASMA_EXPORT DataEngine : public QObject
 {
     Q_OBJECT
@@ -38,32 +54,128 @@ class PLASMA_EXPORT DataEngine : public QObject
         typedef QHash<QString, QVariant> Data;
         typedef QHashIterator<QString, QVariant> DataIterator;
 
-        DataEngine(QObject* parent);
+        /**
+         * Default constructor.
+         *
+         * @param parent The parent object.
+         **/
+        explicit DataEngine(QObject* parent);
         virtual ~DataEngine();
 
+        /**
+         * @return a list of all the data sources currently available via this
+         *         DataEngine
+         **/
         virtual QStringList dataSources();
+
+        /**
+         * Connects a source to an object for data updates. The object must
+         * have a slot with the following signature:
+         *
+         * SLOT(updated(QString, Plasma::DataEngine::Data))
+         *
+         * The data is a QHash of QVariants keyed by QString names, allowing
+         * one data source to provide sets of related data.
+         *
+         * @param source the name of the data source
+         * @param visualization the object to connect the data source to
+         **/
         void connectSource(const QString& source, QObject* visualization);
+
+        /**
+         * Gets the Data associated with a data source.
+         *
+         * The data is a QHash of QVariants keyed by QString names, allowing
+         * one data source to provide sets of related data.
+         *
+         * @param source the data source to retrieve the data for
+         * @return the Data associated with the source; if the source doesn't
+         *         exist an empty data set is returned
+         **/
         Data query(const QString& source);
 
+        /**
+         * Reference counting method. Calling this method increases the count
+         * by one.
+         **/
         void ref();
+
+        /**
+         * Reference counting method. Calling this method decreases the count
+         * by one.
+         **/
         void deref();
+
+        /**
+         * Reference counting method. Used to determine if this DataEngine is 
+         * used.
+         * @return true if the reference count is zero
+         **/
         bool isUsed();
 
-
     Q_SIGNALS:
+        /**
+         * Emitted when a new data source is created
+         * @param source the name of the new data source
+         **/
         void newDataSource(const QString& source);
+
+        /**
+         * Emitted when a data source is removed.
+         * @param source the name of the data source that was removed
+         **/
         void dataSourceRemoved(const QString& source);
 
     protected:
+        /**
+         * This method is called when the DataEngine is started. When this
+         * method is called the DataEngine is fully constructed and ready to be
+         * used. This method should be reimplemented by DataEngine subclasses
+         * which have the need to perform a startup routine.
+         **/
         virtual void init();
+
+        /**
+         * Sets a value for a data source. If the source
+         * doesn't exist then it is created.
+         *
+         * @param source the name of the data source
+         * @param value the data to associated with the source
+         **/
         void setData(const QString& source, const QVariant& value);
+
+        /**
+         * Sets a value for a data source. If the source
+         * doesn't exist then it is created.
+         *
+         * @param source the name of the data source
+         * @param key the key to use for the data
+         * @param value the data to associated with the source
+         **/
         void setData(const QString& source, const QString& key, const QVariant& value);
+
+        /**
+         * Adds an already constructed data source. The DataEngine takes
+         * ownership of the DataSource object.
+         * @param source the DataSource to add to the DataEngine
+         **/
+        void addSource(DataSource* source);
+
 /*        void createDataSource(const QString& source,
                               const QString& domain = QString());*/
+
+        /**
+         * Removes a data source.
+         * @param source the name of the data source to remove
+         **/
         void removeDataSource(const QString& source);
+
+        /**
+         * Removes all data sources
+         **/
         void clearAllDataSources();
 
-    protected Q_SLOTS:
+    private Q_SLOTS:
         void checkForUpdates();
 
     private: