Clarification for terms 'pointer' and 'non-pointer'

[solc42]

Please don't rush with answer =)

Hello, everyone.

First of all, I do realize, that this question may look trivial for an experienced rust user, but for newcomer it does not look clear. Even more I've found very similar clarification issue merged few years ago to rust-lang repo(link below).

So the problem seems to exist.

General term for pointer type does not look clear

The first point is that doc reference, to be honest, is a bit confusing about strict definition about what a pointer type is.

If one comes to reference 10. Type system -> 10.1 Types section, it's clear that

Pointer types:
    - References
    - Raw pointers
    - Function pointers

Okey.

Then if one comes to 10.1.13. Pointer types then, according to section names, pointer types are:

    - References
    - Raw pointers
    - Smart Pointers

So it does not match - nothing about function pointers now, but we have smart pointers.

Now to illustration.

Explanation of dereference operator

Reading the 8.2.4. Operator expressions -> dereference operator section there is branching:

1. When applied to a pointer ...
2. On non-pointer types ...

The documentation here contains explicit reference to 10.1.13. Pointer types, so in "applied to a pointer", pointer seems to be one of those:

• References
• Raw pointers
• Smart Pointers

Then comes part (2) for non-pointer:

On non-pointer types *x is equivalent to *std::ops::Deref::deref(&x) in an immutable place <...>

and non-pointer seems to be about negotiation of pointer, thus about "nor reference nor raw pointer nor smart pointer".

But it is confusing, because doc for trait Deref clearly states that

Deref should only be implemented for smart pointers to avoid confusion.

so non-pointer(thus smart pointer does not match) is illustrated via Deref::deref, and at the same time Deref documentation states that it was designed specifically to accommodate smart pointers.

I would not event bother with an issue, but while googling for clarification for myself, found that there was a similar situation:

• Confusing term ("non-pointer type"s) in docs for 'Deref'/'DerefMut' rust#72335

And documentation for trait is now more clean. But not the reference.

Summing up

• is it possible to make reference definition or some kind of distinction for what exactly term pointer type and non-pointer type mean in documentation, or specify explicitly if context matters
• is it possible clarify the dereference operator documentation? I could make a PR with same clarification phrase Confusing term ("non-pointer type"s) in docs for 'Deref'/'DerefMut' rust#72335, but seems the confusion is a bit more general, cause not only the negotiation part in dereference operator is confusing, but the pointer type/non-pointer type phrase itself.

[scottmcm]

Note that "should" in the Deref docs isn't something that matters to the reference. It needs to define what happens even if you do things you shouldn't.

It would probably be good for the reference to avoid the general term "pointer" altogether, as I don't think it ever really needs it. It can specifically say "raw pointer" or "function pointer" or "reference" when it needs to. (If it's just in a heading it's a grouping construct, not a defining anything, so is non-normative, so is probably fine there.)

Maybe look at how +-vs-Add is defined and piggy-back on that? Because it has the same "on built-in types it does the thing directly, otherwise it goes through Add::add".

"Smart pointers" arguably aren't a thing, so the reference might just be best never talking about them. * uses Deref if it's not a built-in operation on the type, and deciding whether something is or isn't a "smart pointer" doesn't matter for that.

[JanBeh]

Related: Rust std doc issue #91004.