From 48db86483657f3e3e9b6047e434e0a5166048ae7 Mon Sep 17 00:00:00 2001
From: Denis Rouzaud <denis.rouzaud@gmail.com>
Date: Sat, 5 Jan 2019 20:31:10 -0500
Subject: [PATCH] add missing bits to API documentation (#8709)

* add missing bits to API documentation

* API docs

* mark function as deprecated

* Deprecate for Python

* Fix docstrings

* Fix see also link
---
 doc/CMakeLists.txt                       |  2 +
 src/gui/ogr/qgsnewogrconnection.cpp      |  2 +
 src/gui/ogr/qgsnewogrconnection.h        | 12 ++++-
 src/gui/ogr/qgsvectorlayersaveasdialog.h | 57 +++++++++++++++++++++++-
 4 files changed, 70 insertions(+), 3 deletions(-)

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 7802457e8c91..9ad52ff23cbc 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -88,7 +88,9 @@ IF(WITH_APIDOC)
       ${CMAKE_SOURCE_DIR}/src/gui/layertree
       ${CMAKE_SOURCE_DIR}/src/gui/layout
       ${CMAKE_SOURCE_DIR}/src/gui/locator
+      ${CMAKE_SOURCE_DIR}/src/gui/ogr
       ${CMAKE_SOURCE_DIR}/src/gui/processing
+      ${CMAKE_SOURCE_DIR}/src/gui/processing/models
       ${CMAKE_SOURCE_DIR}/src/gui/raster
       ${CMAKE_SOURCE_DIR}/src/gui/symbology
       ${CMAKE_SOURCE_DIR}/src/analysis
diff --git a/src/gui/ogr/qgsnewogrconnection.cpp b/src/gui/ogr/qgsnewogrconnection.cpp
index d6327cc3a1b0..9a4aa2deafd3 100644
--- a/src/gui/ogr/qgsnewogrconnection.cpp
+++ b/src/gui/ogr/qgsnewogrconnection.cpp
@@ -34,7 +34,9 @@ QgsNewOgrConnection::QgsNewOgrConnection( QWidget *parent, const QString &connTy
 {
   setupUi( this );
   connect( btnConnect, &QPushButton::clicked, this, &QgsNewOgrConnection::btnConnect_clicked );
+  Q_NOWARN_DEPRECATED_PUSH
   connect( buttonBox, &QDialogButtonBox::helpRequested, this, &QgsNewOgrConnection::showHelp );
+  Q_NOWARN_DEPRECATED_POP
 
   QgsSettings settings;
   restoreGeometry( settings.value( QStringLiteral( "Windows/OGRDatabaseConnection/geometry" ) ).toByteArray() );
diff --git a/src/gui/ogr/qgsnewogrconnection.h b/src/gui/ogr/qgsnewogrconnection.h
index 62e328c1573d..9273e40adea8 100644
--- a/src/gui/ogr/qgsnewogrconnection.h
+++ b/src/gui/ogr/qgsnewogrconnection.h
@@ -27,9 +27,11 @@
 
 /**
  * \class QgsNewOgrConnection
+ * \ingroup gui
  * \brief Dialog to allow the user to define, test and save connection
  * information for OGR databases
  * \note not available in python bindings
+ * \since QGIS 1.0
  */
 class GUI_EXPORT QgsNewOgrConnection : public QDialog, private Ui::QgsNewOgrConnectionBase
 {
@@ -42,9 +44,17 @@ class GUI_EXPORT QgsNewOgrConnection : public QDialog, private Ui::QgsNewOgrConn
     ~QgsNewOgrConnection() override;
     //! Tests the connection using the parameters supplied
     void testConnection();
-    void showHelp();
+
+    /**
+     * Show the help
+     * \deprecated will be made private with QGIS 4
+     */
+    Q_DECL_DEPRECATED void showHelp() SIP_DEPRECATED;
+
   public slots:
     void accept() override;
+
+  private slots:
     void btnConnect_clicked();
 
   private:
diff --git a/src/gui/ogr/qgsvectorlayersaveasdialog.h b/src/gui/ogr/qgsvectorlayersaveasdialog.h
index a13fc2b6c22c..2414d0987d1f 100644
--- a/src/gui/ogr/qgsvectorlayersaveasdialog.h
+++ b/src/gui/ogr/qgsvectorlayersaveasdialog.h
@@ -30,8 +30,10 @@
 class QgsVectorLayer;
 
 /**
- *  Class to select destination file, type and CRS for ogr layers
- *  \note not available in Python bindings
+ * \ingroup gui
+ * Class to select destination file, type and CRS for ogr layers
+ * \note not available in Python bindings
+ * \since QGIS 1.0
  */
 class GUI_EXPORT QgsVectorLayerSaveAsDialog : public QDialog, private Ui::QgsVectorLayerSaveAsDialogBase
 {
@@ -52,16 +54,58 @@ class GUI_EXPORT QgsVectorLayerSaveAsDialog : public QDialog, private Ui::QgsVec
       AllOptions = ~0 //!< Show all options
     };
 
+    /**
+     * Construct a new QgsVectorLayerSaveAsDialog
+     */
     QgsVectorLayerSaveAsDialog( long srsid, QWidget *parent = nullptr, Qt::WindowFlags fl = nullptr );
+
+    /**
+     * Construct a new QgsVectorLayerSaveAsDialog
+     */
     QgsVectorLayerSaveAsDialog( QgsVectorLayer *layer, int options = AllOptions, QWidget *parent = nullptr, Qt::WindowFlags fl = nullptr );
 
+    /**
+     * The format in which the export should be written.
+     * \see QgsVectorFileWriter::filterForDriver()
+     */
     QString format() const;
+
+    /**
+     * The encoding of the target file.
+     */
     QString encoding() const;
+
+    /**
+     * Returns the target filename.
+     */
     QString filename() const;
+
+    /**
+     * Returns the target layer name
+     */
     QString layername() const;
+
+    /**
+     * Returns a list of additional data source options which are passed to OGR.
+     * Refer to the OGR documentation for the target format for available options.
+     */
     QStringList datasourceOptions() const;
+
+    /**
+     * Returns a list of additional layer options which are passed to OGR.
+     * Refer to the OGR documentation for the target format for available options.
+     */
     QStringList layerOptions() const;
+
+    /**
+     * Returns the internal CRS ID.
+     * \see QgsCoordinateReferenceSystem::srsid()
+     */
     long crs() const;
+
+    /**
+     * Returns a list of attributes which are selected for saving.
+     */
     QgsAttributeList selectedAttributes() const;
     //! Returns selected attributes that must be exported with their displayed values instead of their raw values. Added in QGIS 2.16
     QgsAttributeList attributesAsDisplayedValues() const;
@@ -99,7 +143,16 @@ class GUI_EXPORT QgsVectorLayerSaveAsDialog : public QDialog, private Ui::QgsVec
      */
     void setMapCanvas( QgsMapCanvas *canvas );
 
+    /**
+     * Determines if filtering the export by an extent is activated.
+     * \see filterExtent()
+     */
     bool hasFilterExtent() const;
+
+    /**
+     * Determines the extent to be exported.
+     * \see hasFilterExtent()
+     */
     QgsRectangle filterExtent() const;
 
     /**