How can I find the documentation for the ??= operator?

[speller]

Imagine I'm a newbie and I see the ??= operator in some code. How can I learn about it?

1. What is the type of this operator? When I visit the Operators help page https://www.php.net/manual/en/language.operators.php, I can't find it by searching on the page.
2. I'm clicking randomly on the operator type pages (Operator Precedence, Arithmetic, etc). I can find that it's an Assignment operator on the Operator Precedence page. But when I get to the https://www.php.net/manual/en/language.operators.assignment.php page, I can't find any description. This operator is mentioned in the Other Assignment Operators section with no description, just another type of the operator.
3. Okay, I see that this operator is mentioned as Null Coalesce in the Other Assignment Operators section. When I go to the https://www.php.net/manual/en/language.operators.comparison.php#language.operators.comparison.coalesce page, there's NO description of this operator, it is not mentioned anywhere.
4. Okay, let me try the search field of the php.net website. But again nothing, I get ??= doesn't exist.
5. When I try searching in Google "??=" site:php.net I'm still getting nothing.

Why is getting information about this "secret" operator so difficult? I would suggest the following improvements:

• Mentioning all existing operators on the Operators help page to enable users to quickly identify the type of operator they're looking for by using the browser's search on page function. It probably should be a table with links to corresponding help pages.
• Add explicit documentation for the ??= operator to a corresponding help page.

[damianwadley]

If you're skimming through pages looking for a quick answer, you're probably going to have a hard time. PHP is complicated, and the documentation works much better when you slow down and read it.

The operators page is a good place to start. It's a short page, and the last paragraph says

A full list of PHP operators follows in the section Operator Precedence. The section also explains operator precedence and associativity, which govern exactly how expressions containing several different operators are evaluated.

So then there's the Operator Precedence page. It has a table there of everything, and ??= is in the table, and there it has a link to the Assignment Operators page for more information; documenting everything on this one page would be a bit of a pain...

In the Asssignment Operators page, I see a the part where it says

In addition to the basic assignment operator, there are "combined operators" for all of the binary arithmetic, array union and string operators that allow you to use a value in an expression and then set its value to the result of that expression.

Ah. That sounds like maybe ??= is a "combined operator"? The Assignment by Reference section afterwards doesn't look useful... but after it is a couple more tables, and the Other table says that $a ??= $b is equivalent to $a = $a ?? $b. It also calls that "null coalesce", and the See Also section gives a link. So now the question is what ?? means, assuming you don't already know.

(Truth is that symbol= being shorthand for = combined with symbol is a very common practice across languages...)

The next step is following the link given that places you at the Null Coalescing Operator section within the Comparison page. That... well, doesn't need to be summarized, but it explains what ?? does.

So now you know that ??= is a combined operator of = and ??, and that the latter is the null coalesce operator which does the stuff that it does. Yes, it took a minute of actually reading things to find that answer.

---

Okay, let me try the search field of the php.net website. But again nothing, I get ??= doesn't exist.

When I try searching in Google "??=" site:php.net I'm still getting nothing.

Virtually every search engine in existence doesn't support searching for symbols. So yes, not being able to search for information about operators in any language is a common problem for everyone, which is why it's a Good Thing to know where to find the general operators documentation for your desired language(s).

Mentioning all existing operators on the Operators help page to enable users to quickly identify the type of operator they're looking for by using the browser's search on page function.

Most of the documentation's various chapters and sections start with an introductory page. The Operators chapter is the same way. The very next page after it contains exactly the sort of list you want.

Add explicit documentation for the ??= operator to a corresponding help page.

How so? Do you mean a separate page just about ??=? Does that also mean separate pages for the 63 operators I see in that one table? Is there really anything more needed to explain it than the equivalency shown in that other table, considering that all combined operators follow the exact same pattern?

---

I'm all for improving documentation, and I'm not at all trying to say that everything is fine here and the problem is with you, but keep in mind that sometimes you have to learn how a documentation site is meant to be read before you can read it to find answers.

So there's dumping all information in one page, and creating tons of small pages for every single operator. What other ideas would help you?

[speller]

I know that RTFM is the best answer. But that is not what people expect.

That sounds like maybe ??= is a "combined operator"?

is a very common practice across languages

You assume that the reader person has your mind and the same knowledge as yours to make the same assumptions. While some assumptions may be obvious to you, it doesn't mean they're obvious to everyone. Because your assumptions are based on your existing knowledge. But if the person doesn't have this knowledge, it'll be not easy to come to the same conclusion.

The very next page after it contains exactly the sort of list you want.

I'm okay with that. Just one more click to the user's goal. Who cares about user experience in the documentation, huh? (sarcasm)

Is there really anything more needed to explain

Yes, really need to explain a language operator clearly.

How so? Do you mean a separate page just about ??=?

Does that also mean separate pages for the 63 operators

If there are many operators with the same pattern, then I would suggest listing all of them in a line to make them available for the browser's page search and giving a couple of examples explaining the pattern. It can be a separate page about combined operators. In my opinion, if there's a term "combined operator" in the language, it definitely requires a clear explanation with listing all operators of this type. Probably, a separate page for combined operators would be a good place. With links to/from all other operator types which can be combined.

[sy-records]

https://php.net/??=

[cmb69]

https://php.net/??=

Dark magic. :)

Anyway, this is related to #3519, and https://www.php.net/manual/en/tokens.php is a good starting place to use the search function of your browser.