Add missing /Factory/ annotations to QgsProviderMetadata

Also sipify QgsProviderMetadata and QgsProviderRegistry
qgis · May 6, 2017 · 6502864 · 6502864
1 parent 6af2d30
commit 6502864
Show file tree

Hide file tree

Showing 4 changed files with 221 additions and 97 deletions.
diff --git a/python/auto_sip.blacklist b/python/auto_sip.blacklist
@@ -59,8 +59,6 @@ core/qgssnappingconfig.sip
 core/qgsprojectversion.sip
 core/qgsproperty.sip
 core/qgspropertycollection.sip
-core/qgsprovidermetadata.sip
-core/qgsproviderregistry.sip
 core/qgspythonrunner.sip
 core/qgsrange.sip
 core/qgsrelationmanager.sip

diff --git a/python/core/qgsprovidermetadata.sip b/python/core/qgsprovidermetadata.sip
@@ -1,43 +1,75 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/qgsprovidermetadata.h                                       *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
 
-/** \ingroup core
- * Holds data provider key, description, and associated shared library file information.
 
-   The metadata class is used in a lazy load implementation in
-   QgsProviderRegistry.  To save memory, data providers are only actually
-   loaded via QLibrary calls if they're to be used.  (Though they're all
-   iteratively loaded once to get their metadata information, and then
-   unloaded when the QgsProviderRegistry is created.)  QgsProviderMetadata
-   supplies enough information to be able to later load the associated shared
-   library object.
 
- */
 class QgsProviderMetadata
 {
-%TypeHeaderCode
-#include <qgsprovidermetadata.h>
+%Docstring
+ Holds data provider key, description, and associated shared library file or function pointer information.
+
+ Provider metadata refers either to providers which are loaded via libraries or
+ which are native providers that are included in the core QGIS installation
+ and accessed through function pointers.
+
+ For library based providers, the metadata class is used in a lazy load
+ implementation in QgsProviderRegistry.  To save memory, data providers
+ are only actually loaded via QLibrary calls if they're to be used.  (Though they're all
+ iteratively loaded once to get their metadata information, and then
+ unloaded when the QgsProviderRegistry is created.)  QgsProviderMetadata
+ supplies enough information to be able to later load the associated shared
+ library object.
 %End
 
+%TypeHeaderCode
+#include "qgsprovidermetadata.h"
+%End
   public:
 
+
     QgsProviderMetadata( const QString &_key, const QString &_description, const QString &_library );
 
-    /** This returns the unique key associated with the provider
 
-        This key string is used for the associative container in QgsProviderRegistry
-     */
     QString key() const;
+%Docstring
+ This returns the unique key associated with the provider
 
-    /** This returns descriptive text for the provider
+This key string is used for the associative container in QgsProviderRegistry
+ :rtype: str
+%End
 
-        This is used to provide a descriptive list of available data providers.
-     */
     QString description() const;
+%Docstring
+ This returns descriptive text for the provider
 
-    /** This returns the library file name
+This is used to provide a descriptive list of available data providers.
+ :rtype: str
+%End
 
-        This is used to QLibrary calls to load the data provider.
-     */
     QString library() const;
+%Docstring
+ This returns the library file name
+
+This is used to QLibrary calls to load the data provider.
+ :rtype: str
+%End
+
+
+};
 
 
-}; // class QgsProviderMetadata
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/qgsprovidermetadata.h                                       *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
diff --git a/python/core/qgsproviderregistry.sip b/python/core/qgsproviderregistry.sip
@@ -1,108 +1,194 @@
-/** \ingroup core
-  * A registry / canonical manager of data providers.
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/qgsproviderregistry.h                                       *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+
+
+
+
 
-  This is a Singleton class that manages data provider access.
 
-  Loaded providers may be restricted using QGIS_PROVIDER_FILE environment variable.
-  QGIS_PROVIDER_FILE is regexp pattern applied to provider file name (not provider key).
-  For example, if the variable is set to gdal|ogr|postgres it will load only providers gdal,
-  ogr and postgres.
-*/
 class QgsProviderRegistry
 {
-%TypeHeaderCode
-#include <qgsproviderregistry.h>
+%Docstring
+ A registry / canonical manager of data providers.
+
+ This is a Singleton class that manages data provider access.
+
+ Providers can be either loaded via libraries or native providers that
+ are included in the core QGIS installation and accessed through function pointers.
+
+ Loaded providers may be restricted using QGIS_PROVIDER_FILE environment variable.
+ QGIS_PROVIDER_FILE is regexp pattern applied to provider file name (not provider key).
+ For example, if the variable is set to gdal|ogr|postgres it will load only providers gdal,
+ ogr and postgres.
 %End
 
+%TypeHeaderCode
+#include "qgsproviderregistry.h"
+%End
   public:
 
-    /** Means of accessing canonical single instance */
     static QgsProviderRegistry *instance( const QString &pluginPath = QString::null );
+%Docstring
+Means of accessing canonical single instance
+ :rtype: QgsProviderRegistry
+%End
 
-    /** Virtual dectructor */
     virtual ~QgsProviderRegistry();
 
-    /** Return path for the library of the provider */
     QString library( const QString &providerKey ) const;
+%Docstring
+ Return path for the library of the provider.
+
+ If the provider uses direct provider function pointers instead of a library an empty string will
+ be returned.
+ :rtype: str
+%End
 
-    /** Return list of provider plugins found */
     QString pluginList( bool asHtml = false ) const;
+%Docstring
+Return list of provider plugins found
+ :rtype: str
+%End
 
-    /** Return library directory where plugins are found */
     QDir libraryDirectory() const;
+%Docstring
+ Returns the library directory where plugins are found.
+ :rtype: QDir
+%End
 
-    /** Set library directory where to search for plugins */
     void setLibraryDirectory( const QDir &path );
+%Docstring
+Set library directory where to search for plugins
+%End
+
+    QgsDataProvider *provider( const QString &providerKey,
+                               const QString &dataSource ) /Factory/;
+%Docstring
+ Create a new instance of a provider.
+ \param providerKey identificator of the provider
+ \param dataSource  string containing data source for the provider
+ :return: new instance of provider or NULL on error
+ :rtype: QgsDataProvider
+%End
 
-    /** Create an instance of the provider
-        @param providerKey identificator of the provider
-        @param dataSource  string containing data source for the provider
-        @return instance of provider or NULL on error
-     */
-    QgsDataProvider *provider( const QString & providerKey,
-                               const QString &dataSource );
-
-    /** Return the provider capabilities
-        @param providerKey identificator of the provider
-        @note Added in 2.6
-     */
     int providerCapabilities( const QString &providerKey ) const;
+%Docstring
+ Return the provider capabilities
+\param providerKey identificator of the provider
+.. versionadded:: 2.6
+ :rtype: int
+%End
 
-    /** Returns a widget for selecting layers from a provider.
-     */
-    QWidget *selectWidget( const QString & providerKey,
-                           QWidget *parent = 0, const Qt::WindowFlags &fl = 0 );
-
-    /** Get pointer to provider function
-        @param providerKey identificator of the provider
-        @param functionName name of function
-        @return pointer to function or NULL on error
-     */
-    QFunctionPointer function( const QString & providerKey,
+    QWidget *selectWidget( const QString &providerKey,
+                           QWidget *parent = 0, Qt::WindowFlags fl = Qt::WindowFlags() );
+%Docstring
+ Returns a new widget for selecting layers from a provider.
+ Either the ``parent`` widget must be set or the caller becomes
+ responsible for deleting the returned widget.
+ :rtype: QWidget
+%End
+
+    QFunctionPointer function( const QString &providerKey,
                                const QString &functionName );
+%Docstring
+ Get pointer to provider function
+ \param providerKey identificator of the provider
+ \param functionName name of function
+ :return: pointer to function or NULL on error. If the provider uses direct provider
+ function pointers instead of a library None will be returned.
+ :rtype: QFunctionPointer
+%End
 
-    QLibrary *providerLibrary( const QString &providerKey ) const;
+    QLibrary *providerLibrary( const QString &providerKey ) const /Factory/;
+%Docstring
+ Returns a new QLibrary for the specified ``providerKey``. Ownership of the returned
+ object is transferred to the caller and the caller is responsible for deleting it.
+
+ If the provider uses direct provider function pointers instead of a library None will
+ be returned.
+ :rtype: QLibrary
+%End
 
-    /** Return list of available providers by their keys */
     QStringList providerList() const;
+%Docstring
+Return list of available providers by their keys
+ :rtype: list of str
+%End
 
-    /** Return metadata of the provider or NULL if not found */
     const QgsProviderMetadata *providerMetadata( const QString &providerKey ) const;
+%Docstring
+Return metadata of the provider or NULL if not found
+ :rtype: QgsProviderMetadata
+%End
 
-    /** Return vector file filter string
+    virtual QString fileVectorFilters() const;
+%Docstring
+ Return vector file filter string
 
-      Returns a string suitable for a QFileDialog of vector file formats
-      supported by all data providers.
+Returns a string suitable for a QFileDialog of vector file formats
+supported by all data providers.
 
-      This walks through all data providers appending calls to their
-      fileVectorFilters to a string, which is then returned.
+This walks through all data providers appending calls to their
+fileVectorFilters to a string, which is then returned.
 
-      @note
+\note
 
-      It'd be nice to eventually be raster/vector neutral.
-     */
-    virtual QString fileVectorFilters() const;
-    /** Return raster file filter string
+It'd be nice to eventually be raster/vector neutral.
+ :rtype: str
+%End
+
+    virtual QString fileRasterFilters() const;
+%Docstring
+ Return raster file filter string
 
-      Returns a string suitable for a QFileDialog of raster file formats
-      supported by all data providers.
+Returns a string suitable for a QFileDialog of raster file formats
+supported by all data providers.
 
-      This walks through all data providers appending calls to their
-      buildSupportedRasterFileFilter to a string, which is then returned.
+This walks through all data providers appending calls to their
+buildSupportedRasterFileFilter to a string, which is then returned.
 
-      @note This replaces QgsRasterLayer::buildSupportedRasterFileFilter()
-     */
-    virtual QString fileRasterFilters() const;
-    /** Return a string containing the available database drivers */
+.. note::
+
+   This replaces QgsRasterLayer.buildSupportedRasterFileFilter()
+ :rtype: str
+%End
     virtual QString databaseDrivers() const;
-    /** Return a string containing the available directory drivers */
+%Docstring
+Return a string containing the available database drivers
+ :rtype: str
+%End
     virtual QString directoryDrivers() const;
-    /** Return a string containing the available protocol drivers */
+%Docstring
+Return a string containing the available directory drivers
+ :rtype: str
+%End
     virtual QString protocolDrivers() const;
+%Docstring
+Return a string containing the available protocol drivers
+ :rtype: str
+%End
 
     void registerGuis( QWidget *widget );
 
+
+
   private:
-    /** Ctor private since instance() creates it */
-    QgsProviderRegistry( QString pluginPath );
+    QgsProviderRegistry( const QString &pluginPath );
 }; // class QgsProviderRegistry
+
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/qgsproviderregistry.h                                       *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/