6

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:

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.

  • For a better understanding of API Documentation, it will be very helpful to be aware of Object Oriented Programming. For example, 'what is a class/subclass/superclass, an object, a function (returning/not returning a value), inheritance' etc. Otherwise, only explaining of "how to read, how to understand API Docs" won't be enough. – Kadir Şahbaz Apr 17 '18 at 15:00
3

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.

  • Aha, this explains a lot. Are you aware of any resources giving more information on the API docs? Or the C++ terminology that is used in the API docs? – Lennert Apr 17 '18 at 11:18
  • Ok. Your reply is excellent for answering the questions about QgsVectorFileWriter, but for the moment I will leave the question open because it is also more broadly related to documentation on the API docs. Thanks! – Lennert Apr 17 '18 at 14:13
  • I suggest you edit the title as "Understanding QGIS API documentation", otherwise, it remains as related to QgsVectorFileWriter. – Kadir Şahbaz Apr 17 '18 at 14:21
  • That was the original title, but PolyGeo changed it ;). – Lennert Apr 17 '18 at 14:26
3

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

enter image description here

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.