Skip to content
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

Undocument use paths. #665

Merged
merged 1 commit into from
Apr 8, 2020
Merged

Undocument use paths. #665

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 2 additions & 6 deletions src/items/use-declarations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,13 +82,9 @@ In this example, the module `quux` re-exports two public names defined in

## `use` Paths

Paths in `use` items must start with a crate name or one of the [path
qualifiers] `crate`, `self`, `super`, or `::`. `crate` refers to the current
crate. `self` refers to the current module. `super` refers to the parent
module. `::` can be used to explicitly refer to a crate, requiring an extern
crate name to follow.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The snippet above you're removing seems roughly accurate? Rather than removing it, can we just add your note?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is misleading, because it seems to imply there is something special about use paths or that the first segment is restricted somehow. This hasn't been true since uniform paths (which feels like an eternity ago, but was only in January!).

The use path is really any "vaild" path for some definition of "valid".

The "paths" chapter describes what all these qualifiers mean, so I don't think they need to be repeated.

From my incomplete notes (which are likely outdated), paths can also start with:

  • Item? in the current scope. (Item may be the wrong word.)
  • A macro in the macro_use prelude.
  • An item in the prelude.
  • Built-in type.
  • Built-in attribute (but can't be used for some reason).
  • Built-in tool module (but can't be used for some reason).

Plus a bunch of restrictions on what can't be used (associated items, built-in macros, type parameters, local variables, Self types, impl items, etc).

> **Note**: This section is incomplete.

An example of what will and will not work for `use` items:
Some examples of what will and will not work for `use` items:
<!-- Note: This example works as-is in either 2015 or 2018. -->

```rust
Expand Down