Thanks for your feedback!
I added an documentation page specifically about .desktop launchers: Desktop files for menu integration
I also updated the reference explanation of the icon key to better explain that this is only used for the snap store, not for the desktop launch menu.: https://snapcraft.io/docs/snapcraft-top-level-metadata#heading--icon
Let me know if this stuff is still unclear.