Documentation bug in Mix_SetSoundFonts regarding FluidSynth

[cspiegel]

Mix_SetSoundFonts includes this in its documentation:

You may specify multiple paths in a single string by separating them with semicolons; they will be searched in the order listed.

I assume "searched in the order listed" means that the first-listed will be prioritized. However, this is not correct. In fact, the last-listed has the highest priority, when used with FluidSynth. The Mac backend looks like it also uses SoundFonts, but I'm not sure if this applies to it: I don't know what order things are loaded there.

The FluidSynth backend does this:

Mix_EachSoundFont(fluidsynth_load_soundfont, music->synth)

Which iterates over the provided SoundFonts in order, calling fluidsynth_load_soundfont for each one. fluidsynth_load_soundfont calls fluid_synth_sfload, which is documented:

The newly loaded SoundFont will be put on top of the SoundFont stack. Presets are searched starting from the SoundFont on the top of the stack, working the way down the stack until a preset is found.

So, the last added SoundFont goes on the top of the stack, and the stack is searched downward.

Testing agrees with this: the last-listed SoundFont does take priority, i.e. its instruments are used, with earlier-listed SoundFonts only being consulted for missing instruments.

A fix is simple (either change the docs or iterate backward over the list), but I'm not sure which is preferred.