[RFC] glib: document coordinate spaces of annot-related PopplerRectangles

I'm been trying to get my head around the different coordinate systems, I hope I documented this correctly, but I'm not 100% sure. Under the premise that I got it correctly (so completely ignore if that's wrong), then I have some wonders about the API, specially wondering how can we make it better:

• There's some asymmetry between poppler_annot_set_rectangle and poppler_annot_get_rectangle, which means fetching and setting the same rectangle as below might modify the location of the annotation, if the page is rotated. This can be counter-intuitive and means consumers must treat consider different coordinate systems depending on what they are doing. IIUC this is not the case in the QT bindings, where all the coordinates for annotations are in normalized coords. Changing the behavior of get_rectangle will break consumers, so if we want to fix this, we'd need new API? Example:

PopplerRectangle *rect;
pps_annot_get_rectangle(annot, rect);
pps_annot_set_rectangle(annot, rect); // Annotation might change place if the page is rotated!

• It seems to me that PopplerAnnotMapping serves as part of that missing API. It provides the annotations linking them to a rectangle in normalized coordinates. Although it works, it's remarkably different to what the QT bindings do, where they just provide a list of annotations. Doing so, has the potential to simplify client code. Therefore, if we are able to modify or add new API for get_rectangle to provide normalized coordinates, then we could also add new API that just returns a GList * or PopplerAnnot. Does that make sense?
• Finally, it seems like the GLib bindings are not using the CTM transform, contrary to QT bindings. However, they still do rotation and crob_box transformations. This is a part where I'm way out of my depth, but that called my attention and wanted to comment in case somebody had any thoughts