Document api breakages and add more doxymentation

qgis · Dec 20, 2016 · 1ad6e0b · 1ad6e0b
1 parent 590a51e
commit 1ad6e0b
Show file tree

Hide file tree

Showing 5 changed files with 45 additions and 10 deletions.
diff --git a/doc/api_break.dox b/doc/api_break.dox
@@ -261,6 +261,7 @@ should now call QgsCoordinateReferenceSystem::invalidateCache() and QgsCoordinat
 - QgsRendererV2DataDefinedMenus was removed. Use QgsDataDefinedButton instead.
 - QgsLegacyHelpers.
 - QgsProviderCountCalcEvent and QgsProviderExtentCalcEvent. These classes were unused in QGIS core and unmaintained.
+- QgsEditorWidgetConfig was removed. Use QVariantMap instead.
 
 
 General changes        {#qgis_api_break_3_0_global}
@@ -890,6 +891,7 @@ QgsFieldExpressionWidget        {#qgis_api_break_3_0_QgsFieldExpressionWidget}
 ------------------------
 
 - The setLayer( QgsVectorlayer* ) slot has been removed. Use the setLayer( QgsMapLayer* ) slot instead.
+- registerGetExpressionContextCallback has been removed in favor of registerExpressionContextGenerator
 
 
 QgsFields        {#qgis_api_break_3_0_QgsFields}
@@ -899,12 +901,6 @@ QgsFields        {#qgis_api_break_3_0_QgsFields}
 - fieldNameIndex has been renamed to lookupField. See the API documentation for details.
 
 
-QgsFieldExpressionWidget        {#qgis_api_break_3_0_QgsFieldExpressionWidget}
-------------------------
-
-- registerGetExpressionContextCallback has been removed in favor of registerExpressionContextGenerator
-
-
 QgsFieldProxyModel        {#qgis_api_break_3_0_QgsFieldProxyModel}
 ------------------
 
@@ -971,8 +967,23 @@ plugins calling this method will need to be updated.
 QgsEditorWidgetRegistry        {#qgis_api_break_3_0_QgsEditorWidgetRegistry}
 -----------------------
 
-- The signature of isFieldSupported() has been changed to return an unsigned (how good it supports the given field)
-and to const-correct it.
+- The signature of isFieldSupported() has been changed to return an unsigned
+  integer (how good it supports the given field) and is now const.
+
+QgsEditorWidgetFactory         {#qgis_api_break_3_0_QgsEditorWidgetFactory}
+----------------------
+
+- `readEditorConfig` has been removed. The configuration is read and written
+  from and to a QVariantMap automatically.
+- `readConfig` has been removed. The configuration is read and written
+  from and to a QVariantMap automatically.
+- `writeConfig` has been removed. The configuration is read and written
+  from and to a QVariantMap automatically.
+- `representValue` has been removed. Use QgsFieldKit::representValue() instead
+- `sortValue` has been removed. Use QgsFieldKit::representValue() instead
+- `alignmentFlag` has been removed. Use QgsFieldKit::representValue() instead
+- `createCache` has been removed. Use QgsFieldKit::representValue() instead
+
 
 QgsGraduatedRenderer        {#qgis_api_break_3_0_QgsGraduatedRenderer}
 --------------------

diff --git a/python/core/qgsapplication.sip b/python/core/qgsapplication.sip
@@ -398,6 +398,12 @@ static void qtgui_UpdatePyArgv(PyObject *argvlist, int argc, char **argv)
      */
     static QgsRuntimeProfiler* profiler();
 
+    /**
+     * Provides access to the field kit registry.
+     *
+     * @note Added in QGIS 3.0
+     */
+    static QgsFieldKitRegistry* fieldKitRegistry();
   public slots:
 
     /** Causes the application instance to emit the settingsChanged() signal. This should

diff --git a/src/core/qgsfieldkit.h b/src/core/qgsfieldkit.h
@@ -21,6 +21,18 @@
 
 class QgsVectorLayer;
 
+/**
+ * \ingroup core
+ * A field kit helps to handle and display values for a field.
+ *
+ * It allows for using a shared configuration with the editor widgets
+ * for representation of attribute values.
+ * Field kits normally have one single instance which is managed by the
+ * QgsFieldKitRegistry. Custom field kits should be registered there and
+ * field kits for use within code should normally be obtained from there.
+ *
+ * This is an abstract base class and will always need to be subclassed.
+ */
 class CORE_EXPORT QgsFieldKit
 {
   public:
@@ -48,7 +60,7 @@ class CORE_EXPORT QgsFieldKit
     /**
      * If the default sort order should be overwritten for this widget, you can transform the value in here.
      *
-     * @return By default the value is returned unmodified.
+     * @returns an unmodified value by default.
      *
      * @note Added in 3.0
      */

diff --git a/src/core/qgsfieldkitregistry.h b/src/core/qgsfieldkitregistry.h
@@ -22,6 +22,12 @@
 
 class QgsFieldKit;
 
+/**
+ * \ingroup core
+ * The QgsFieldKitRegistry manages registered classes of QgsFieldKit.
+ * A reference to the QgsFieldKitRegistry can be obtained from
+ * QgsApplication::fieldKitRegistry().
+ */
 class CORE_EXPORT QgsFieldKitRegistry : public QObject
 {
     Q_OBJECT

diff --git a/src/core/qgsvectorlayer.h b/src/core/qgsvectorlayer.h
@@ -794,7 +794,7 @@ class CORE_EXPORT QgsVectorLayer : public QgsMapLayer, public QgsExpressionConte
     virtual QString loadNamedStyle( const QString &theURI, bool &theResultFlag ) override;
 
     /** Read the symbology for the current layer from the Dom node supplied.
-     * @param node node that will contain the symbology definition for this layer.
+     * @param layerNode node that will contain the symbology definition for this layer.
      * @param errorMessage reference to string that will be updated with any error messages
      * @return true in case of success.
      */