improve include!() docs

[durka]

The docs are:

Parse the current given file as an expression.

This is generally a bad idea, because it's going to behave unhygienically.

• current given file? wat
• "as an expression" is incorrect -- it could be an item or statement according to context
• The second sentence is vague and confusing if you aren't familiar with hygiene.
• Behavior WRT relative paths is not specified (for include_str! it is).

include!() is widely used for generated code these days, so the doc should be more informative and clearly explain in which situations include!() is a bad idea. Maybe even have an example of including generated code from $OUT_DIR.

Part of #29381.

[frewsxcv]

This was presumably fixed by #36404.