Adding documentation for data providers

src/core/qgsvectorlayer.h

@@ -236,7 +236,228 @@ class CORE_EXPORT QgsVectorLayer : public QgsMapLayer
       QList<GroupData> mGroups;
     };
 
-    /** Constructor */
+    /** Constructor - creates a vector layer
+     *
+     * The QgsVectorLayer is constructed by instantiating a data provider.  The provider
+     * interprets the supplied path (url) of the data source to connect to and access the
+     * data.  Some providers and url formats are described below.
+     *
+     * @param  path  The path or url of the parameter.  Typically this encodes
+     *               parameters used by the data provider as url query items.
+     * @param  baseName The name used to represent the layer in the legend
+     * @param  providerLib  The name of the data provider, eg "memory", "postgres"
+     *
+     * Data providers
+     * ==============
+     *
+     * Memory data providerType (memory)
+     * ------------------------
+     *
+     * The memory data provider is used to construct in memory data, for example scratch
+     * data or data generated from spatial operations such as contouring.  There is no
+     * inherent persistent storage of the data.  The data source uri is constructed.  The
+     * url specifies the geometry type ("point", "linestring", "polygon",
+     * "multipoint","multilinestring","multipolygon"), optionally followed by url parameters
+     * as follows:
+     *
+     * - crs=definition
+     *   Defines the coordinate reference system to use for the layer.
+     *   definition is any string accepted by QgsCoordinateReferenceSystem::createFromString()
+     *
+     * - index=yes
+     *   Specifies that the layer will be constructed with a spatial index
+     *
+     * - field=name:type(length,precision)
+     *   Defines an attribute of the layer.  Multiple field parameters can be added
+     *   to the data provider definition.  type is one of "integer", "double", "string".
+     *
+     * An example url is "Point?crs=epsg:4326&field=id:integer&field=name:string(20)&index=yes"
+     *
+     * OGR data provider (ogr)
+     * -----------------
+     *
+     * Accesses data using the OGR drivers (http://www.gdal.org/ogr/ogr_formats.html). The url
+     * is the OGR connection string.
+     *
+     * GDAL data provider (gdal)
+     * ------------------
+     *
+     * Access raster data using the GDAL drivers (http://www.gdal.org/formats_list.html)
+     *
+     * Spatialite data provider (spatialite)
+     * ------------------------
+     *
+     * Access data in a spatialite database. The url defines the connection parameters, table,
+     * geometry column, and other attributes.  The url can be constructed using the
+     * QgsDataSourceURI class.
+     *
+     * Postgresql data provider (postgres)
+     * -------------------------
+     *
+     * Connects to a postgresql database.  The url defines the connection parameters, table,
+     * geometry column, and other attributes.  The url can be constructed using the
+     * QgsDataSourceURI class.
+     *
+     * Microsoft SQL server data provider (mssql)
+     * ----------------------------------
+     *
+     * Connects to a Microsoft SQL server database.  The url defines the connection parameters, table,
+     * geometry column, and other attributes.  The url can be constructed using the
+     * QgsDataSourceURI class.
+     *
+     * SQL Anywhere data provider (sqlanywhere)
+     * -------------------------
+     *
+     * Connects to an SQLanywhere database.  The url defines the connection parameters, table,
+     * geometry column, and other attributes.  The url can be constructed using the
+     * QgsDataSourceURI class.
+     *
+     * WMS (web mapping service) data provider (wms)
+     * ---------------------------------------
+     *
+     * Provider for raster data in a supplied by a web mapping service.
+     *
+     * The url is the connection string for the WMS service.
+     *
+     * WFS (web feature service) data provider (wfs)
+     * ---------------------------------------
+     *
+     * Provider for vector data in a supplied by a web feature service.
+     *
+     * The url is the connection string for the WFS service.
+     *
+     * WCS (web coverage service) data provider (wcs)
+     * ----------------------------------------
+     *
+     * The url is the connection string for the WCS service.
+     *
+     * Delimited text file data provider (delimitedtext)
+     * ---------------------------------
+     *
+     * Access data in a delimited text file, for example CSV files generated by
+     * spreadsheets. The contents of the file are split into columns based on specified
+     * delimiter characters.  Each record may be represented spatially either by an
+     * X and Y coordinate column, or by a WKT (well known text) formatted columns.
+     *
+     * The url defines the filename, the formatting options (how the
+     * text in the file is divided into data fields, and which fields contain the
+     * X,Y coordinates or WKT text definition.  The options are specified as url query
+     * items.
+     *
+     * At its simplest the url can just be the filename, in which case it will be loaded
+     * as a CSV formatted file.
+     *
+     * The url may include the following items:
+     *
+     * - encoding=UTF-8
+     *
+     *   Defines the character encoding in the file.  The default is UTF-8.  To use
+     *   the default encoding for the operating system use "System".
+     *
+     * - type=(csv|regexp|whitespace|plain)
+     *
+     *   Defines the algorithm used to split records into columns. Records are
+     *   defined by new lines, except for csv format files for which quoted fields
+     *   may span multiple records.  The default type is csv.
+     *
+     *   + "csv" splits the file based on three sets of characters:
+     *      delimiter characters, quote characters,
+     *      and escape characters.  Delimiter characters mark the end
+     *      of a field. Quote characters enclose a field which can contain
+     *      delimiter characters, and newlines.  Escape characters cause the
+     *      following character to be treated literally (including delimiter,
+     *      quote, and newline characters).  Escape and quote characters must
+     *      be different from delimiter characters. Escape characters that are
+     *      also quote characters are treated specially - they can only
+     *      escape themselves within quotes.  Elsewhere they are treated as
+     *      quote characters.  The defaults for delimiter, quote, and escape
+     *      are ',', '"', '"'.
+     *   +  "regexp" splits each record using a regular expression (see QRegExp
+     *      documentation for details).
+     *   +  "whitespace" splits each record based on whitespace (on or more whitespace
+     *      characters.  Leading whitespace in the record is ignored.
+     *   +  "plain" is provided for backwards compatibility.  It is equivalent to
+     *      CSV except that the default quote characters are single and double quotes,
+     *      and there is no escape characters.
+     *
+     * - delimiter=characters
+     *
+     *   Defines the delimiter characters used for csv and plain type files, or the
+     *   regular expression for regexp type files.  It is a literal string of characters
+     *   except that "\t" may be used to represent a tab character.
+     *
+     * - quote=characters
+     *
+     *   Defines the characters that are used as quote characters for csv and plain type
+     *   files.
+     *
+     * - escape=characters
+     *
+     *   Defines the characters used to escape delimiter, quote, and newline characters.
+     *
+     * - skipLines=n
+     *
+     *   Defines the number of lines to ignore at the beginning of the file (default 0)
+     *
+     * - useHeader=(yes|no)
+     *
+     *   Defines whether the first record in the file (after skipped lines) contains
+     *   column names (default yes)
+     *
+     * - xField=column yField=column
+     *
+     *   Defines the name of the columns holding the x and y coordinates for XY point geometries.
+     *   If the useHeader is no (ie there are no column names), then this is the column
+     *   number (with the first column as 1).
+     *
+     * - decimalPoint=c
+     *
+     *   Defines a character that is used as a decimal point in the X and Y columns.
+     *   The defualt is '.'.
+     *
+     * - wktField=column
+     *
+     *   Defines the name of the columns holding the WKT geometry definition for WKT geometries.
+     *   If the useHeader is no (ie there are no column names), then this is the column
+     *   number (with the first column as 1).
+     *
+     * - geomType=(point|line|polygon|none)
+     *
+     *   Defines the geometry type for WKT type geometries.  QGis will only display one
+     *   type of geometry for the layer - any others will be ignored when the file is
+     *   loaded.  By default the provider uses the type of the first geometry in the file.
+     *   Use geomType to override this type.
+     *
+     *   geomType can also be set to none, in which case the layer is loaded without
+     *   geometries.
+     *
+     * - crs=crsstring
+     *
+     *   Defines the coordinate reference system used for the layer.  This can be
+     *   any string accepted by QgsCoordinateReferenceSystem::createFromString()
+     *
+     * - quiet
+     *
+     *   Errors encountered loading the file will not be reported in a user dialog if
+     *   quiet is included (They will still be shown in the output log).
+     *
+     * GPX data provider (gps)
+     * -----------------
+     *
+     * Provider reads tracks, routes, and waypoints from a GPX file.  The url
+     * defines the name of the file, and the type of data to retrieve from it
+     * ("track", "route", or "waypoint").
+     *
+     * An example url is "/home/user/data/holiday.gpx?type=route"
+     *
+     * Grass data provider (grass)
+     * -------------------
+     *
+     * Provider to display raster data in a GRASS GIS layer.
+     *
+     *
+     *
+     */
     QgsVectorLayer( QString path = QString::null, QString baseName = QString::null,
                     QString providerLib = QString::null, bool loadDefaultStyleFlag = true );