Understanding QGIS API documentation [closed]

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 inheritance 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:

• Seeking learning resources for PyQGIS
• Understanding QGIS API documentation to write Python code using QgsVectorLayer?

But as far as I know, 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

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

Answer 2

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 the 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, the 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 the 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.

There is a book I'd like to recommend: Building Mapping Applications with QGIS. It contains a chapter gives an extensive explanation about QGIS API.