That is all. This sounds like a bug to me, since it is quite capable of creating new displays -- it just lies about what adapter it will do so on. Which means I can't reliably get information about it (with al_get_monitor_info, which by the way should be called al_get_display_adapter_info for consistency). I don't know if this is an issue on other platforms too.

When it returns -1, it means it's up to the OS to decide and you haven't specified a preference. If you care about windows showing up on a particular display, you have to call al_set_new_display_adapter() first.
It's not obvious across different platforms what the "default" works out to be, which is why the default option is "don't care" rather than a hard-coded value (0, for instance) or a buggy attempt at guessing what the default should be.

Unless you're actually calling al_set_new_display_adapter() and it's ignored. That's a bug.

Then the documentation should stop lying:

It does not do this. The fact that there is only one API function that even uses this index, and it becomes useless since the function doesn't return anything relevant in the one case where you actually want to use it, makes this a pretty serious issue. If you can't actually return the video adapter index new displays will be created on, this function shouldn't exist.

I don't actually care what adapter it will show up on. What I do want to know is a few details about that adapter.

It should be documented that ALLEGRO_DEFAULT_DISPLAY_ADAPTER is a valid return value from that function, I agree.

The shortcoming is that it cannot be used with al_get_monitor_info().

Unfortunately there isn't really a way to 100% accurately guess which monitor the window is going to appear on if you leave it up to the OS. My X code has some hackish code that will try and emulate what a smart wm would do in some modes (dual X Screen's without xinerama), but its not something we should try and do for all modes on all OSs.

I agree that makes the al_get_new_display_adapter function useless in the general case, but if you've called al_set_new_display_adapter, it becomes somewhat useful.

Only in the sense that you already know what you set the new display adapter to.

Added a sentence to the docs.

Maybe not. Could have been some other code you don't have direct control over. But like I said, in the general case, it isn't exactly useful.