[Pkg-owncloud-commits] [qtkeychain] 03/115: Apidocs for the people

[Sandro Knauß]

This is an automated email from the git hooks/post-receive script.

hefee-guest pushed a commit to branch master
in repository qtkeychain.

commit f700615472add2c4fc9fd910d9408bb9da528d88
Author: Frank Osterfeld <frank.osterfeld at kdab.com>
Date:   Thu Oct 27 20:46:23 2011 +0200

    Apidocs for the people
---
 keychain.h       | 69 +++++++++++++++++++++++++++++++++++++++++++++++++-------
 keychain_mac.cpp |  6 ++---
 2 files changed, 64 insertions(+), 11 deletions(-)

diff --git a/keychain.h b/keychain.h
index 544cc9b..9e209aa 100644
--- a/keychain.h
+++ b/keychain.h
@@ -11,33 +11,86 @@
 
 #include <QtCore/QString>
 
+/**
+ *
+ */
 class Keychain {
 public:
+    /**
+     * Creates a Keychain object.
+     *
+     * @param service The service name of your service/application. Used as identifier,
+     *        to disambiguate and avoid clashes with other applications.
+     */
     explicit Keychain( const QString& service );
+
+    /**
+     * Destructor
+     */
     ~Keychain();
 
+    /**
+     * Error codes
+     */
     enum Error {
-        NoError=0,
-        PasswordNotFound,
-        CouldNotDeleteExistingPassword,
-        AccessDenied,
-        EntryAlreadyExists,
-        OtherError
+        NoError=0, /*< No error occurred, operation was successful */
+        PasswordNotFound, /*< For the given account no password was found */
+        CouldNotDeletePassword, /*< Could not delete existing password */
+        AccessDeniedByUser, /*< User denied access to keychain */
+        AccessDenied, /*< Access denied for other reasons */
+        EntryAlreadyExists, /*< There is already a password for the given account and overwriting was not enforced */
+        OtherError /*< Something else went wrong (errorString() might provide details) */
     };
 
+    /**
+     * Overwrite mode when writing passwords to the keychain
+     */
     enum OverwriteMode {
-        DoNotOverwrite,
-        ForceOverwrite
+        DoNotOverwrite, /*< Do not overwrite existing entries */
+        ForceOverwrite  /*< Replace old passowrd by new one */
     };
 
+    /**
+     * The service name used as identifier.
+     */
     QString service() const;
+
+    /**
+     * The error code of the last operation.
+     */
     Error error() const;
+
+    /**
+     * Human-readable error description of the last operation.
+     */
     QString errorString() const;
 
+    /**
+     * Stores a @p password in the keychain, for a given @p account.
+     * error() and errorString() hold the result of the write operation.
+     *
+     * @param account the account to store a password for
+     * @param the password to store
+     * @param om Whether to overwrite existing passwords
+     */
     void writePassword( const QString& account,
                         const QString& password,
                         OverwriteMode om=DoNotOverwrite );
+
+    /**
+     * Reads the @p password for an @p account from the keychain.
+     * error() and errorString() hold the result of the read operation.
+     *
+     * @param account the account ot read the password for
+     */
     QString readPassword( const QString& account );
+
+    /**
+     * Deletes the @p password for an @p account from the keychain.
+     * error() and errorString() hold the result of the read operation.
+     *
+     * @param account The account to delete the password for
+     */
     void deletePassword( const QString& account );
 
 private:
diff --git a/keychain_mac.cpp b/keychain_mac.cpp
index 0dd210a..860174f 100644
--- a/keychain_mac.cpp
+++ b/keychain_mac.cpp
@@ -88,7 +88,7 @@ Keychain::Error Keychain::Private::writePasswordImpl( const QString& account,
             }
             Error derr = deletePasswordImpl( account, err );
             if ( derr != NoError )
-                return CouldNotDeleteExistingPassword;
+                return CouldNotDeletePassword;
             else
                 return writePasswordImpl( account, password, ov, err );
         }
@@ -107,7 +107,7 @@ Keychain::Error Keychain::Private::deletePasswordImpl( const QString& account,
     QString pw;
     const OSStatus ret1 = readPw( &pw, service, account, &ref );
     if ( ret1 == errSecItemNotFound )
-        return NoError;
+        return NoError; // No item stored, we're done
     if ( ret1 != noErr ) {
         //TODO map error code, set errstr
         return OtherError;
@@ -117,6 +117,6 @@ Keychain::Error Keychain::Private::deletePasswordImpl( const QString& account,
     if ( ret2 == noErr )
         return NoError;
     //TODO map error code, set errstr
-    return OtherError;
+    return CouldNotDeletePassword;
 }
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/qtkeychain.git