Python's own docs' search doesn't seem to recognize the <= symbol. Google does, but if one doesn't know that, then one won't try it. Google inconsistently decides when and which symbols are considered word chars, and I don't know whether the rules are even documented.

Perhaps `help` should be the canonical way to find initial info on operators. The more reliably useful `help` is, the more people will recommend and get in the habit of using it.

The current docs for `help` say that a string argument will be interpreted as an identifier, keyword, or "documentation topic" (such as "LISTS"), but it says nothing about symbols.

On 3.6.6, calling `help('+')` prints out the documentation for operator precedence, which is kind of jumping into the intermediate part of the pool. Instead, it can explain that the symbol is used as both a unary and binary operator (giving examples of each), say that addition is typically numerical add or string concat, mention that the operator looks for the special method __add__/__pos__, point to related operators (like +=), and point to more info on operators in general (which will point to operator overloading).

On Wed, Jun 19, 2019, 15:19 Chris Angelico <rosuav@gmail.com> wrote:
On Thu, Jun 20, 2019 at 4:31 AM Guido van Rossum <guido@python.org> wrote:
>
> On Wed, Jun 19, 2019 at 11:27 AM Chris Angelico <rosuav@gmail.com> wrote:
>>
>> On Thu, Jun 20, 2019 at 2:07 AM Franklin? Lee
>> <leewangzhong+python@gmail.com> wrote:
>> > For example,
>> >     if (A <: B or A <: C) and A <: D:
>> > is not much better than
>> >     if issubclass(A, (B, C)) and issubclass(A, D):
>> > especially if you don't know what either of those mean. You can search
>> > for issubclass, but you can't search for <:.
>>
>> Please can people stop trotting out this tired argument? I just typed
>> "<:" (without the quotes) into Google - or rather, into my Chrome
>> omnibar - and the first hit was a Stack Overflow question regarding
>> the "<:" operator in Scala, the second is Scala documentation about
>> "Upper Type Bounds" which looks plausible, and then there are a few
>> others that may or may not be related.
>>
>> Symbols CAN be searched for, both in Google and in many documentation tools.
>
>
> It's still harder. E.g. the wikipedia article on subtyping does not show in the search results for "<:", and searching for "<: wikipedia" ignores the "<:" entirely and just searches for "wikipedia".
>

Fair. But it keeps being said as "you can't search for", which at best
is an exaggeration. There is a related problem with symbols in that
they often have multiple meanings (if you search for info about "@" in
a Python context, you'll get both matrix multiplication and
decorators), but they are still searchable.

(And maybe if people stop using "they're not searchable" as an
argument, the tools that ARE completely unable to search for symbols
will be seen as flawed tools.)

ChrisA
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-leave@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/YMFBBDQHNVULN6L6RKUJW3PMVJJHAFCK/
Code of Conduct: http://python.org/psf/codeofconduct/