Understanding QGIS API documentation

Question

Is there an introduction or guidelines how to read the QGIS API documentation?

For example, I want to write a vector layer. A quick search brings me to the API documentation page of QgsVectorFileWriter.

This is a very long page with an inheritence diagram, different classes, public classes, public membership functions,... but I don't fully understand what this means.

I can figure out that I need the QgsVectorFileWriter::QgsVectorFileWriter function, but also in this part I have some questions:

• here are three identical(?) functions listed?
• which variables are mandatory and which are optional?

I've found some useful resources on pyqgis at:

• Learning resources for PyQGIS?
• Understanding the QGIS API documentation to write python code

but afaik these resources don't give a gentle introduction on how to read the API docs.

I think understanding how to read the API documentation would really help me to write my own code rather than searching for examples.

Answer 1

Actually, QGIS API Documentation (and maybe many API Docs) is written in C++ terminology. At first, users who don't know about C++ find it hard to understand API Docs. However, over time it's getting easier. Sometimes, documentation which is written in Python terminology may not contain enough information about library. And getting used to C++ terminology is inevitable.

Let me answer your questions briefly:

• Here are three identical(?) functions listed?

It means that you can use writeAsVectorFormat in three different ways with different parameters for different goals. Such functions are called overloaded functions, and normally, you don't need such functions in Python and they come from C++.

• Which variables are mandatory and which are optional?

If any parameter definition doesn't include 'equal sign (=)', i.e. layer, fileName and fileEncoding in following lines, it is mandatory. Which includes 'equal sign' is optional, i.e. destCRS and driverName and if you don't specify, value next to it will pass to function by default, for example "GPKG" for driverName.

QgsVectorFileWriter::writeAsVectorFormat  (QgsVectorLayer * layer,
                                           const QString &  fileName,
                                           const QString &  fileEncoding,
                                           const QgsCoordinateReferenceSystem & 
                                                  destCRS = QgsCoordinateReferenceSystem(),
                                           const QString &  driverName = "GPKG",
                                           .
                                           .
                                           .

QgsVectorLayer, QString, QgsCoordinateReferenceSystem etc. are data types, and parameters which you pass to function have to match them. That's, layer has to be an instance of QgsVectorLayer, fileNamehas to be a string and so on. If they don't match, you encounter an error as in QgsVectorFileWriter.writeAsVectorFormat differents Qgis2.xx Qgis3.XX.

Answer 2

The new official PyQGIS API documentation should take care of this issue since it translates the original C++ code documentation to Python.