document and export the class

dataengineconsumer.h

@@ -22,17 +22,54 @@
 
 #include <QtCore/QUrl>
 
+#include <plasma/plasma_export.h>
+
 namespace Plasma
 {
 
 class DataEngine;
 class DataEngineConsumerPrivate;
 
-class DataEngineConsumer
+/**
+ * @class DataEngineConsumer plasma/dataengineconsumer.h <Plasma/DataEngineConsumer>
+ *
+ * @brief A class that makes it safe and easy to use DataEngines
+ *
+ * DataEngineConsumer provides access to DataEngines, which are internally reference
+ * counted and shared between all users of them. The only public method provided is
+ * dataEngine which returns engines upon request.
+ *
+ * When the DataEngineConsumer class is deleted, all engines accessed using it are
+ * de-referenced and possibly deleted (in the case that there are no other users of
+ * the engine in question).
+ *
+ * DataEngineConsumer can be subclassed by other C++ classes to allow this simple
+ * API to be used directly from these classes in a convenient manner.
+ **/
+class PLASMA_EXPORT DataEngineConsumer
 {
 public:
+    /**
+     * Constructs a DataEngineConsumer
+     **/
     DataEngineConsumer();
     ~DataEngineConsumer();
+
+    /**
+     * Returns a Plasma::DataEngine. It never returns a null pointer, and the
+     * DataEngine returned should not be deleted. All DataEngines will be dereferenced
+     * once this DataEngineConsumer instance is deleted.
+     *
+     * It is safe and fast to request the same engine more than once.
+     *
+     * @param name the name of the DataEngine. This corresponds to the plugin name
+     *             of the DataEngine.
+     * @param location if a non-empty URI is passed in, then a connection with a
+     *                 remote DataEngine at the location is attempted to be made.
+     *                 The returned pointer is a proxy object for this connection.
+     *                 In the common case, location is always an empty URI (QUrl())
+     *                 and the DataEngine is loaded locally.
+     */
     DataEngine *dataEngine(const QString &name, const QUrl &location = QUrl());
 
 private: