be more explicit in docs, on when/how to delete services

svn path=/trunk/KDE/kdelibs/; revision=1135278

dataengine.h

@@ -235,9 +235,11 @@ NoAlignment) const;
         QString pluginName() const;
 
         /**
-         *  Initializes and returns a new service from the name that was set with setDefaultService.
+         * Initializes and returns a new service from the name that was set
-         *  (service name is set internally). Sends a DataEngine* to the created service via the QVariantList.
+         * with setDefaultService. (service name is set internally). Remember to dispose
-         *  Note that you have to dispose of the Service* manually if you do not pass a valid parent.
+         * of the Service* when you are finished with it (even if a parent is passed)
+         * A DataEngine* is sent to the created service via the QVariantList arguments.
+         * 
          *  @see setDefaultService
          *  @param the parent of the object, if any, for the returned service
          *  @return the newly created service

service.h

@@ -73,6 +73,20 @@ class ServicePrivate;
  * Plasma::ServiceJob *job = service->startOperationCall(op);
  * connect(job, SIGNAL(finished(KJob*)), this, SLOT(jobCompeted()));
  * @endcode
+ *
+ * Please remember, the service needs to be deleted when it will no longer be
+ * used. This can be done manually or by these (perhaps easier) alternatives:
+ *
+ * If it is needed throughout the lifetime of the object:
+ * @code
+ * service->setParent(this);
+ * @endcode
+ *
+ * If the service will not be used after just one operation call, use:
+ * @code
+ * connect(job, SIGNAL(finished(KJob*)), service, SLOT(deleteLater()));
+ * @endcode
+ *
  */
 class PLASMA_EXPORT Service : public QObject
 {