* api docu

* remove the name methods which just wrapped the setObjectName stuff anyways

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

datasource.cpp

@@ -48,16 +48,6 @@ DataSource::~DataSource()
     delete d;
 }
 
-QString DataSource::name()
-{
-    return objectName();
-}
-
-void DataSource::setName(const QString& name)
-{
-    setObjectName(name);
-}
-
 const DataEngine::Data DataSource::data() const
 {
     return d->data;

datasource.h

@@ -27,7 +27,17 @@
 
 namespace Plasma
 {
-
+/**
+ * @brief A set of data exported via a DatEngine
+ *
+ * Plasma::DataSource wraps the data exported by a DataEngine
+ * implementation, providing a generic wrapper for the data.
+ *
+ * A DataSource may have zero or more associated pieces of data which
+ * are keyed by strings. The data itself is stored as QVariants. This allows
+ * easy and flexible retrieval of the information associated with this object
+ * without writing DataSource or DataEngine specific code in visualizations.
+ **/
 class PLASMA_EXPORT DataSource : public QObject
 {
     Q_OBJECT
@@ -36,17 +46,39 @@ class PLASMA_EXPORT DataSource : public QObject
         typedef QHash<QString, DataSource*> Dict;
         typedef QHash<QString, Dict> Grouping;
 
+        /**
+         * Constructs a default DataSource, which has no name or data
+         * associated with it
+         **/
         explicit DataSource(QObject* parent = 0);
         virtual ~DataSource();
 
-        QString name();
+        /**
-        void setName(const QString&);
+         * Returns the data for this DataSource
+         **/
         const DataEngine::Data data() const;
+
+        /**
+         * Set a value for a key. This also marks this source as needing
+         * to signal an update. After calling this, a call to checkForUpdate()
+         * is done by the engine. This allows for batching updates.
+         *
+         * @param key a string used as the key for the data
+         * @param value a QVariant holding the actual data
+         **/
         void setData(const QString& key, const QVariant& value);
 
+        /**
+         * Checks for whether the data has changed and therefore an update
+         * signal needs to be emitted.
+         **/
         void checkForUpdate();
 
     Q_SIGNALS:
+        /**
+         * Emitted when the data has been updated, allowing visualization to
+         * reflect the new data.
+         **/
         void updated(const QString& source, const Plasma::DataEngine::Data& data);
 
     private: