From 2b4b22883d299ded4dac9f8ec1047b7618af766e Mon Sep 17 00:00:00 2001
From: Alex Merry <kde@randomguy3.me.uk>
Date: Wed, 11 Jul 2007 01:24:43 +0000
Subject: [PATCH] Make the APIDOX not lie, and change the logic to make sense
 (loadDataEngine will always return a data engine - it just might not be
 valid).

I changed it this way, rather than changing the test to
engine->isValid(), since all the plasmoids written so far
blindly assume a valid pointer is returned.  (In fact, they
all blindly assume the correct data engine is returned, but
at least this way they shouldn't crash plasma :-P)


svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=686301
---
 applet.cpp |  5 ++---
 applet.h   | 16 ++++++++++++++--
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/applet.cpp b/applet.cpp
index 7e6e7e04f..7f1c7ddcf 100644
--- a/applet.cpp
+++ b/applet.cpp
@@ -144,12 +144,11 @@ DataEngine* Applet::dataEngine(const QString& name)
     }
 
     DataEngine* engine = DataEngineManager::self()->loadDataEngine(name);
-    if (engine) {
+    if (engine->isValid()) {
         d->loadedEngines.append(name);
-        return engine;
     }
 
-    return 0;
+    return engine;
 }
 
 void Applet::constraintsUpdated()
diff --git a/applet.h b/applet.h
index 34f6aba96..0107341cd 100644
--- a/applet.h
+++ b/applet.h
@@ -90,9 +90,21 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
         KConfigGroup globalAppletConfig() const;
 
         /**
-         * Ensures that the DataEngine named name is loaded and ready to be used.
+         * Loads the given DataEngine
          *
-         * @return returns true on success, false on failure
+         * Tries to load the data engine given by @p name.  Each engine is
+         * only loaded once, and that instance is re-used on all subsequent
+         * requests.
+         *
+         * If the data engine was not found, an invalid data engine is returned
+         * (see DataEngine::isValid()).
+         *
+         * Note that you should <em>not</em> delete the returned engine.
+         *
+         * @param name Name of the data engine to load
+         * @return pointer to the data engine if it was loaded,
+         *         or an invalid data engine if the requested engine
+         *         could not be loaded
          */
         DataEngine* dataEngine(const QString& name);