This attribute should be used for debugging purposes only. It is not suitable in production code.
Wow what a daft comment 
Yeah. I have been using per-function optimize attribute in production code for years, without noticing this warning in documentation. If they were serious about this, why not emit a compile-time message so that users could actually see it, and maybe silence manually it with something like -Wno-optimize-attribute-warning.
In any case, never noticed any problems whatsoever. I tend to use it when the module is -Os for obvious reasons but some particular function, usually an interrupt handler or a smaller function the ISR calls needs to be -O2 or even -O3, again for other obvious reasons.
Separating it to a different compilation unit is of course an option but when they clearly are part of the same module and share same static variables etc. anyway, such extra separation makes the project more messy, while the optimize attribute is neat and tidy.
But then again, in situations where it matters you have to verify the compiler output (execution time, code size) manually
anyway and I fully expect to do that again every time compiler versions change,
even if I used file-scope optimization settings. Luckily only very small % of actual projects are timing-critical code like that, so I'm not too afraid of changing versions - just that you shouldn't do it like every day for no reason whatsoever.