The docs for GI annotations mention the (method) annotation, but don’t say anything more enlightening than, ‘This function is a method.’ I thought I was supposed to use it on all my methods, but this has turned out not to be the case, because it breaks the method names in the output of g-ir-scanner. For example, htsp_connection_close, a method of HtspConnection, gets the name connection_close instead of close, if I annotate it with (method).
So how/when/why is (method) really supposed to be used?
The bugzilla bug seems to be a little clearer. It seems to indicate this is for marking a static function (ie. instance-less) as a method, so that the bindings make them callable from an instance.
gdk_display_get_default() might be a bad example here, but currently in GJS you would do this:
let display = Gdk.Display.get_default();
Presumably if it were marked (method) you could call:
// Getting a display
let display = new Gtk.Label().get_display();
// Calling a static method from an instance
let defaultDisplay = display.get_default();