Dox++

qgis · Feb 3, 2019 · eba5409 · eba5409
1 parent 1699520
commit eba5409
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 0 deletions.
diff --git a/python/core/auto_generated/qgscredentials.sip.in b/python/core/auto_generated/qgscredentials.sip.in
@@ -32,7 +32,34 @@ signal destroyed() to be notified of the deletion
     virtual ~QgsCredentials();
 
     bool get( const QString &realm, QString &username /In,Out/, QString &password /In,Out/, const QString &message = QString() );
+%Docstring
+Requests credentials for the specified ``realm``.
+
+If existing credentials exist for the given ``realm``, these will be returned. Otherwise the credential
+handler will prompt for the correct username and password.
+
+The retrieved or user-entered details will be stored in ``username`` and ``password``.
+
+Optionally, a specific ``message`` can be used to advise users of the context for the credentials request.
+
+.. note::
+
+   This method will not automatically store the newly obtained credentials. Callers must
+   manually call put() after verifying that the obtained credentials are correct.
+
+.. seealso:: :py:func:`put`
+%End
+
     void put( const QString &realm, const QString &username, const QString &password );
+%Docstring
+Stores the correct ``username`` and ``password`` for the specified ``realm``.
+
+These values will be used for all future calls to get() for the same ``realm``, without requesting
+users to re-enter them. It is the caller's responsibility to ensure that only valid ``username`` and ``password``
+combinations are used with this method.
+
+.. seealso:: :py:func:`get`
+%End
 
     bool getMasterPassword( QString &password /In,Out/, bool stored = false );
 

diff --git a/src/core/qgscredentials.h b/src/core/qgscredentials.h
@@ -47,7 +47,32 @@ class CORE_EXPORT QgsCredentials
      */
     virtual ~QgsCredentials() = default;
 
+    /**
+     * Requests credentials for the specified \a realm.
+     *
+     * If existing credentials exist for the given \a realm, these will be returned. Otherwise the credential
+     * handler will prompt for the correct username and password.
+     *
+     * The retrieved or user-entered details will be stored in \a username and \a password.
+     *
+     * Optionally, a specific \a message can be used to advise users of the context for the credentials request.
+     *
+     * \note This method will not automatically store the newly obtained credentials. Callers must
+     * manually call put() after verifying that the obtained credentials are correct.
+     *
+     * \see put()
+     */
     bool get( const QString &realm, QString &username SIP_INOUT, QString &password SIP_INOUT, const QString &message = QString() );
+
+    /**
+     * Stores the correct \a username and \a password for the specified \a realm.
+     *
+     * These values will be used for all future calls to get() for the same \a realm, without requesting
+     * users to re-enter them. It is the caller's responsibility to ensure that only valid \a username and \a password
+     * combinations are used with this method.
+     *
+     * \see get()
+     */
     void put( const QString &realm, const QString &username, const QString &password );
 
     bool getMasterPassword( QString &password SIP_INOUT, bool stored = false );