[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    KDE/kdelibs/kdecore/config
From:       Alex Merry <kde () randomguy3 ! me ! uk>
Date:       2008-12-15 21:31:34
Message-ID: 1229376694.371315.28169.nullmailer () svn ! kde ! org
[Download RAW message or body]

SVN commit 897370 by alexmerry:

Apidocs fixes



 M  +73 -31    kconfigbackend.h  


--- trunk/KDE/kdelibs/kdecore/config/kconfigbackend.h #897369:897370
@@ -38,7 +38,13 @@
 class QDateTime;
 
 /**
- * \class KConfigBackend kconfigbackend.h <KConfigBackEnd>
+ * \class KConfigBackend kconfigbackend.h <KConfigBackend>
+ *
+ * Provides the implementation for accessing configuration sources.
+ *
+ * KDELibs only provides an INI backend, but this class can be used
+ * to create plugins that allow access to other file formats and
+ * configuration systems.
  */
 class KDECORE_EXPORT KConfigBackend : public QObject, public KShared
 {
@@ -47,25 +53,37 @@
     Q_FLAGS(WriteOption)
 
 public:
-    /** returns a KConfigBackend object to be used with KConfig
-     * @param fileName the absolute file name
-     * @param system the configuration system to use. if the given system is
-     *               not found or an empty string is passed in, then it tries to determine the
-     *               correct backend to return.
+    /**
+     * Creates a new KConfig backend.
+     *
+     * If no @p system is given, or the given @p system is unknown, this method tries
+     * to determine the correct backend to use.
+     *
+     * @param componentData the owning component
+     * @param fileName      the absolute file name of the configuration file
+     * @param system        the configuration system to use
+     * @return a KConfigBackend object to be used with KConfig
      */
     static KSharedPtr<KConfigBackend> create(const KComponentData& componentData,
                                              const QString& fileName = QString(),
                                              const QString& system = QString());
 
-    /** registers mappings from directory/file to configuration system
+    /**
+     * Registers mappings from directories/files to configuration systems
+     *
+     * Allows you to tell KConfigBackend that create() should use a particular
+     * backend for a particular file or directory.
+     *
+     * @warning currently does nothing
+     *
      * @param entryMap the KEntryMap to build the mappings from
      */
     static void registerMappings(const KEntryMap& entryMap);
 
-    /** destroys the backend */
+    /** Destroys the backend */
     virtual ~KConfigBackend();
 
-    /** options passed to parseConfig. */
+    /** Allows the behaviour of parseConfig() to be tuned */
     enum ParseOption {
         ParseGlobal = 1, /// entries should be marked as @em global
         ParseDefaults = 2, /// entries should be marked as @em default
@@ -74,22 +92,24 @@
     /// @typedef typedef QFlags<ParseOption> ParseOptions
     Q_DECLARE_FLAGS(ParseOptions, ParseOption)
 
-    /** options passed to writeConfig. */
+    /** Allows the behaviour of writeConfig() to be tuned */
     enum WriteOption {
         WriteGlobal = 1 /// only write entries marked as "global"
     };
     /// @typedef typedef QFlags<WriteOption> WriteOptions
     Q_DECLARE_FLAGS(WriteOptions, WriteOption)
 
-    /** Return value from parseConfig. */
+    /** Return value from parseConfig() */
     enum ParseInfo {
-        ParseOk, /// object opened read/write
-        ParseImmutable, /// object is @em immutable
-        ParseOpenError /// there was an error opening object
+        ParseOk, /// the configuration was opened read/write
+        ParseImmutable, /// the configuration is @em immutable
+        ParseOpenError /// the configuration could not be opened
     };
 
     /**
-     * Read permanent storage.
+     * Read persistent storage
+     *
+     * @param locale the locale to read entries for (if the backend supports localized entries)
      * @param pWriteBackMap the KEntryMap where the entries are placed
      * @param options @see ParseOptions
      * @return @see ParseInfo
@@ -99,55 +119,77 @@
                                   ParseOptions options = ParseOptions()) = 0;
 
     /**
-     * Write the @em dirty entries to permanent storage.
+     * Write the @em dirty entries to permanent storage
+     *
+     * @param locale the locale to write entries for (if the backend supports localized entries)
      * @param entryMap the KEntryMap containing the config object's entries.
      * @param options @see WriteOptions
+     * @param data the component that requested the write
+     *
+     * @return @c true if the write was successful, @c false if writing the configuration failed
      */
     virtual bool writeConfig(const QByteArray& locale, KEntryMap& entryMap,
                              WriteOptions options, const KComponentData &data) = 0;
 
     /**
-     * is this object writable?
-     * @note This function @b MUST be implemented by sub-classes.
+     * If isWritable() returns false, writeConfig() will always fail.
+     *
+     * @return @c true if the configuration is writable, @c false if it is immutable
      */
     virtual bool isWritable() const = 0;
     /**
-     * When isWritable returns false, return an error message to
+     * When isWritable() returns @c false, return an error message to
      * explain to the user why saving configuration will not work.
+     *
+     * The return value when isWritable() returns @c true is undefined.
+     *
+     * @returns a translated user-visible explanation for the configuration
+     *          object not being writable
      */
     virtual QString nonWritableErrorMessage() const = 0;
     /**
-     * get the read/write status of the configuration object.
-     * @note This function @b MUST be implemented by sub-classes.
+     * @return the read/write status of the configuration object
+     *
+     * @see KConfigBase::AccessMode
      */
     virtual KConfigBase::AccessMode accessMode() const = 0;
     /**
-     * create the enclosing object of @em this object.
-     * @note This function @b MUST be implemented by sub-classes.
+     * Create the enclosing object of the configuration object
+     *
+     * For example, if the configuration object is a file, this should create
+     * the parent directory.
      */
     virtual void createEnclosing() = 0;
 
-    /** Set the file path.
-     * @param path the absolute file path.
+    /**
+     * Set the file path.
+     *
      * @note @p path @b MUST be @em absolute.
-     * @note This function @b MUST be implemented by sub-classes.
+     *
+     * @param path the absolute file path
      */
     virtual void setFilePath(const QString& path) = 0;
 
     /**
-     * lock the file
+     * Lock the file
      */
     virtual bool lock(const KComponentData& componentData) = 0;
+    /**
+     * Release the lock on the file
+     */
     virtual void unlock() = 0;
+    /**
+     * @return @c true if the file is locked, @c false if it is not locked
+     */
     virtual bool isLocked() const = 0;
 
-    /** when was the object last modified?
-     * @return the date/time when the object was last modified.
+    /**
+     * @return the date and time when the object was last modified
      */
     QDateTime lastModified() const;
-    /** The path to the object. */
+    /** @return the absolute path to the object */
     QString filePath() const;
-    /** The size of the object. */
+    /** @Return the size of the object */
     qint64 size() const;
 
 protected:
[prev in list] [next in list] [prev in thread] [next in thread]