Commit ae5fe1aa218c30afb419d64aa121f3c575fe2f95 improved the gdk_window_create_similar_image_surface documentation by making it clear that the height and width are in pixels, not device-space units, and that they are not multiplied by the scaling factor.

That's good, but it is still confusing if you are dealing with all of these:
 (a) cairo_surface_create_similar
 (b) cairo_surface_create_similar_image
 (c) gdk_window_create_similar_image_surface

(a) inherits the device scale, (b) doesn't and (c) does. I think (b) and (c) sound deceptively similar that it is worth mentioning this. Never mind that the documentation for (b) is wrong about the units of its parameters.

I filed a cairo bug here:
https://bugs.freedesktop.org/show_bug.cgi?id=99094

Some conversation on #gtk+ about why (b) doesn't inherit the scale:

11:23 <rishi> alex: Hey! Why doesn't cairo_surface_create_similar_image         
      inherit the device scale?
11:23 <Company> rishi: because an image has pixels
11:24 <Company> rishi: and you can't have a 100px image have 100px with a 2x    
      scale
11:24 <rishi> Company: But an image surface can have a device scale.
11:25 <rishi> So, if I want to create a similar image surface, I'd expect the   
      scale to be copied.
11:25 <Company> rishi: but if you want 100px, we don't know if you really mean  
      100px at 2x scale or if you mean 200px
11:27 <Company> it's always wrong in 50% of cases
11:27 <rishi> Company: Note the *similar*. Otherwise I'd have used              
      cairo_image_surface_create.
11:27 <alex> If you loaded a jpg, and you want to show it, you don't want the   
      scale applied
11:27 <rishi> Either way, it would be good if this was explicitly mentioned.
11:27 <alex> similar just means "same backend"
11:27 <Company> rishi: push a doc fix!
11:27 <alex> or "efficient format for that backend"
11:28 <rishi> Because cairo_image_surface_create inherits the scale.
11:28 <rishi> Company: Yeah, I was going to do that. :)
11:28 <Company> rishi: what create_similar() does is usually shm-map the image  
      memory, so it can easier be copied to X, but that's about it
11:29 <alex> cairo_image_surface_create inherit scales from what?
11:29 <Company> cairo_image_surface_create() can't inherit anything
11:29 <rishi> alex: From the given surface.
11:30 <alex> it doesn't take an image
11:30 <Company> rishi probably means create_similar() on an image surface
11:30 <rishi> Oh, no. Wait.
11:30 <alex> surface
11:30 <rishi> I meant cairo_surface_create_similar.
11:30 <Company> but that's different
11:30 <alex> that is very different
11:30 <alex> thats an "abstract" surface
11:30 <Company> the equivalent is gdk_window_create_similar()
11:30 <Company> but create_image_surface() is about pixels
11:31 <alex> not something you can rely on to shove exact pixels into
11:31 <rishi> Company: alex: I know that it is different *after* reading the    
      code. :)