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

@@ -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()

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);