Skip to content

improve include!() docs #36387

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
4 tasks
durka opened this issue Sep 10, 2016 · 1 comment
Closed
4 tasks

improve include!() docs #36387

durka opened this issue Sep 10, 2016 · 1 comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools

Comments

@durka
Copy link
Contributor

durka commented Sep 10, 2016 •
edited
Loading

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.
@durka durka changed the title docs for include!() are bad improve include!() docs Sep 10, 2016
@alexispurslane alexispurslane mentioned this issue Sep 11, 2016
Merged
alexispurslane added a commit to alexispurslane/rust that referenced this issue Sep 12, 2016
@alexispurslane
Fixed issue rust-lang#36387
3660a79
bors added a commit that referenced this issue Oct 2, 2016
@bors
Auto merge of #36404 - christopherdumas:master, r=GuillaumeGomez
8991ffc 
Documentation change to macros.rs for `includes!`

I'm not sure if this documentation is clear or extensive enough, but this is just to get started on the problem, fixes issue #36387.
@steveklabnik steveklabnik removed the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Mar 10, 2017
@steveklabnik steveklabnik added A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools and removed A-docs labels Mar 23, 2017
@frewsxcv
Copy link
Member

frewsxcv commented Jun 8, 2017

This was presumably fixed by #36404.

@frewsxcv frewsxcv closed this as completed Jun 8, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@steveklabnik @durka @frewsxcv