What does the --hint option in grub2's search command do?

--hint is used to select which partition to select when there are multiple matched partition. By default the 1st matched one is selected.

Suppose there are 2 storage device with label boot as follows

hd0,msdos1
hd1,msdos7

then the command :

search --set=root --label freepool --hint hd1,msdos7

will select hd1,msdos7 instead of hd0,msdos1