# "and", "or", bitwise or shortcircuit, what we get searching docs
**URL:** https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263
**Category:** New to Julia
**Created:** [September 8, 2020, 1:27pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263 "2020-09-08T13:27:37Z")
**Posts on this page:** 20
**Page:** 3
### Author:  [@tomerarnon](https://discourse.julialang.org/u/tomerarnon)
#### Post date: [September 9, 2020, 1:38pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/42 "2020-09-09T13:38:20Z")
> [@Tamas\_Papp](#):
>
> apropos
Wow! I did not know about this, and it’s incredible that this exists!
---
### Author:  [@lmiq](https://discourse.julialang.org/u/lmiq)
#### Post date: [September 9, 2020, 1:46pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/43 "2020-09-09T13:46:47Z")
> [@Tamas\_Papp](#):
>
> So `?plus` should take you to `+` , etc? (if not, please explain why).
Let me recall that I started this thread because I am teaching students to program in Julia and they ran, with some frequency, in this problem.
I do not think we have to add to the docs everything we imagine that can be a problem, but the things that people effectively report to be a problem (if, of course, more people agree with that).
Of course, I never had any issue with expectations and use of the plus sign.
---
### Author:  [@devel-chm](https://discourse.julialang.org/u/devel-chm)
#### Post date: [September 9, 2020, 1:51pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/44 "2020-09-09T13:51:49Z")
I am a new Julia user using the REPL and vim as my development approach.
The ?/help mode of the REPL isn’t helpful in discovery. It appears to match the specific names of the functions/operators/… Using apropos() is too broad.
If the help mode had a partial apropos option (maybe ?word in help mode) to search the 1-line brief descriptions as well as the names of things that would address many of the problems of discovery. It could return the list of commands and the short descriptions one line each. Then you could search directly for the appropriate term.
For example, ?and would find &, && and others and the output might look like this:
> & Bitwise and.
> && Short-circuiting boolean AND.
> …
Then the user could read the help docs for &, &&, or whatever as desired.
---
### Author:  [@Henrique\_Becker](https://discourse.julialang.org/u/Henrique_Becker)
#### Post date: [September 9, 2020, 1:52pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/45 "2020-09-09T13:52:48Z")
Copying part of my GitHub answer here:
> My argument however, is that our target public is exactly people who are searching something they do now know how to express. If this happened often with `+` , then I would suggest adding `?plus` . However, `+` for `plus` is (afaik) universal, and nobody ever had this doubt. `&&` and `||` are much more arbitrary symbols (specially the fact they are doubled and not just `&` and `|` ) and not shared by all programming languages while, at the same time, are very basic concepts implemented by all programming languages, and needed often for the most basic programs.
To complement, I would say to people outside of Computer Science logical `and` and `or` are not common knowledge as addition and the `+` symbol are (any child today know them).
---
### Author:  [@Oscar\_Smith](https://discourse.julialang.org/u/Oscar_Smith)
#### Post date: [September 9, 2020, 3:34pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/46 "2020-09-09T15:34:53Z")
I think it would be good to for example link `inv` to `\`. Common words and punctuation are really hard to search
---
### Author:  [@opera\_malenky](https://discourse.julialang.org/u/opera_malenky)
#### Post date: [September 9, 2020, 3:52pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/47 "2020-09-09T15:52:03Z")
Not to get off-topic, but is there an obvious way I’m missing of searching _just_ the manual contents? When I am looking through the manual, and I type things into the search bar [at the top of the page](https://docs.julialang.org/en/v1/manual/getting-started/), it shows results for millions of function definitions from base and stdlib, which makes the search pretty useless for me.
---
### Author:  [@kevbonham](https://discourse.julialang.org/u/kevbonham)
#### Post date: [September 9, 2020, 5:00pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/48 "2020-09-09T17:00:58Z")
> [@Tamas\_Papp](#):
>
> So `?plus` should take you to `+` , etc? (if not, please explain why).
Good question. I personally wouldn’t advocate for it, but I’m trying to cast myself into the mindset of when I was first learning programming, I think I would have searched `+`, `add`, and `sum` in that order, but not `plus`. But `add` currently doesn’t have any meaning, so that perhaps makes your point as well. I think I agree with @Henrique_Becker’s point, but with low conviction, I just wanted to make sure we were discussing the right thing 🙂
---
### Author:  [@lmiq](https://discourse.julialang.org/u/lmiq)
#### Post date: [September 9, 2020, 5:17pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/49 "2020-09-09T17:17:58Z")
The way the `+` operator was documented is a good example, I think. Although it is likely that it will never cause any confusion, the help entry is much more clear than that of `&&` and `||`.
```julia
help?> +
search: +
+(x, y...)
Addition operator. x+y+z+... calls this function with all arguments, i.e. +(x, y, z, ...).
Examples
≡≡≡≡≡≡≡≡≡≡
julia> 1 + 20 + 4
25
julia> +(1, 20, 4)
25
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
dt::Date + t::Time -> DateTime
The addition of a Date with a Time produces a DateTime. The hour, minute, second, and millisecond parts of the Time are used along
with the year, month, and day of the Date to create the new DateTime. Non-zero microseconds or nanoseconds in the Time type will
result in an InexactError being thrown.
```
```julia
help?> &&
search: &&
x && y
Short-circuiting boolean AND.
```
---
### Author:  [@Palli](https://discourse.julialang.org/u/Palli)
#### Post date: [September 9, 2020, 9:30pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/50 "2020-09-09T21:30:31Z")
> [@Tamas\_Papp](#):
>
> So `?plus` should take you to `+` , etc? (if not, please explain why).
Well, it’s logical, so I added `plus` but mostly not for that reason. We do not need to be complete with `multiply`, while `division` is non-trivial (that I didn’t address), with `/`, and e.g. other operators `\` and `÷` and `//`.
> [@lmiq](#):
>
> The way the `+` operator was documented is a good example, I think. Although it is likely that it will never cause any confusion
It will, by the absence of mentioning concatenating strings. I just made a PR for `plus` (for numbers, and yes, strings, while there the wrong term), also adding to `+` and `||` (as people learn that from SQL).
---
### Author:  [@simeonschaub](https://discourse.julialang.org/u/simeonschaub)
#### Post date: [September 9, 2020, 9:44pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/51 "2020-09-09T21:44:10Z")
I appreciate your effort, but did you follow the discussion in [https://github.com/JuliaLang/julia/issues/37469](https://github.com/JuliaLang/julia/issues/37469)? `plus` was actually used as an example of what we didn’t want the REPL help to be.
---
### Author:  [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)
#### Post date: [September 10, 2020, 7:55am UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/52 "2020-09-10T07:55:07Z")
> [@Palli](#):
>
> Well, it’s logical, so I added `plus` but mostly not for that reason. We do not need to be complete with `multiply` , while `division` is non-trivial (that I didn’t address), with `/` , and e.g. other operators `\` and `÷` and `//` .
That was meant as a [reductio ad absurdum](https://en.wikipedia.org/wiki/Reductio_ad_absurdum) argument. Sorry for the misunderstanding, I did not expect that someone would actually do it.
---
### Author:  [@stevengj](https://discourse.julialang.org/u/stevengj)
#### Post date: [September 10, 2020, 12:34pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/53 "2020-09-10T12:34:54Z")
> [@lmiq](#):
>
> The second page, which is “Control flow” defines “Short circuit evaluation”, and then the “&&” and “||” operators, which actually behave as we would expect from “and” and “or”. But that page does not mention that those are the “and” and “or” we would generally want:
I added some explanation on this point to that section of the manual, so hopefully matters should be improved: [clarify && and || by stevengj · Pull Request #37489 · JuliaLang/julia · GitHub](https://github.com/JuliaLang/julia/pull/37489)
---
### Author:  [@Henrique\_Becker](https://discourse.julialang.org/u/Henrique_Becker)
#### Post date: [September 10, 2020, 12:51pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/54 "2020-09-10T12:51:09Z")
> [@Tamas\_Papp](#):
>
> That was meant as a [reductio ad absurdum](https://en.wikipedia.org/wiki/Reductio_ad_absurdum) argument.
This hardly qualify as a reduction ad absurdum. You used a [slippery slope argument](https://en.wikipedia.org/wiki/Slippery_slope), in which you consider there is no middle ground where some operators will be documented this way but not all, it is only a reduction ad absurdum if, for some reason: (1) it was strictly necessary to document all operators this way if just one or two of them were documented this way; (2) everyone agreed that documenting all operators this way is impractical or absurd.
---
### Author:  [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)
#### Post date: [September 10, 2020, 2:11pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/55 "2020-09-10T14:11:37Z")
> [@Henrique\_Becker](#):
>
> you consider there is no middle ground where some operators will be documented this way but not all
Yes, based on recent discussions like this I don’t really think there is a practical limit to this phenomenon.
If something surprises someone because they did not read the manual and this is considered a sufficient reason to complain about the docs (both the docstrings and the manual), all kinds of things can and will be added.
Eg if `?and` should take you to `&&` just because Python has it, then it is difficult to explain why `?%*%` (matrix multiplication in R) should not have a docstring that suggests `*`. Not _all_ such operators will be documented (that is a very large universe), just those which happen to be of interest to somebody.
---
### Author:  [@Henrique\_Becker](https://discourse.julialang.org/u/Henrique_Becker)
#### Post date: [September 10, 2020, 2:35pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/56 "2020-09-10T14:35:23Z")
Do not forgot the second point of the slippery slope
> (2) everyone agreed that documenting all operators this way is impractical or absurd.
While avoiding to inconvenience readers wanting to read all the manual is reason enough to restrict the manual scope, increasing the number of docstrings does not share the same problem, as docstrings are queried on demand, and do not inconvenience people that are not confused by the added docstring.
Again, you ignore the previous argument that `and` and `or` are the names of such operations (or at least, how someone who does not know the symbols may reasonably expect them to be named), they are not searched only “because Python has it”. I have never, for example, thought of suggesting we add an entry for `++` about string concatenation because Haskell use this operator. However, `concatenation` maybe would be useful (while I think it is not worth the effort).
---
### Author:  [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)
#### Post date: [September 11, 2020, 7:59am UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/57 "2020-09-11T07:59:40Z")
> [@Henrique\_Becker](#):
>
> increasing the number of docstrings does not share the same problem, as docstrings are queried on demand, and do not inconvenience people that are not confused by the added docstring
You are right. I just don’t think that adding docstrings for symbols which aren’t actual objects is elegant or necessary.
> [@Henrique\_Becker](#):
>
> you ignore the previous argument that `and` and `or` are the names of such operations (or at least, how someone who does not know the symbols may reasonably expect them to be named)
I am not sure about this. The names are “logical and” or “boolean and” etc. “and” itself is ambiguous, as it could be bitwise and.
Also, importantly, `&&` and `||` are not operators in Julia — they are control flow syntax.
The important thing is that a user who is actually looking for either of these operators (bitwise or boolean) should be able to find it.
But note that `?` does not do text search for any other symbol: the right solution is to do that, ie use `apropos` or `?"..."`. However, apparently not enough people know about these, so maybe the startup message could mention these options.
---
### Author:  [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)
#### Post date: [September 11, 2020, 8:03am UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/58 "2020-09-11T08:03:35Z")
Opened an issue:
[https://github.com/JuliaLang/julia/issues/37523](https://github.com/JuliaLang/julia/issues/37523)
---
### Author:  [@tomerarnon](https://discourse.julialang.org/u/tomerarnon)
#### Post date: [September 11, 2020, 10:09am UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/59 "2020-09-11T10:09:21Z")
> [@Tamas\_Papp](#):
>
> The important thing is that a user who is actually looking for either of these operators (bitwise or boolean) should be able to find it.
>
> But note that `?` does not do text search for any other symbol: the right solution is to do that, ie use `apropos` or `?"..."` . However, apparently not enough people know about these, so maybe the startup message could mention these options.
I don’t think apropos currently solves this particular problem:
```julia
julia> apropos("bitwise and")
Base.:&
julia> apropos("logical and") # nothing
julia> apropos("boolean and") # nothing
julia> apropos("and")
# Hundreds of results. Notably `&&` isn't even among them.
```
---
### Author:  [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)
#### Post date: [September 11, 2020, 10:14am UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/60 "2020-09-11T10:14:02Z")
Yes, that should be fixed.
---
### Author:  [@Oscar\_Smith](https://discourse.julialang.org/u/Oscar_Smith)
#### Post date: [September 11, 2020, 1:03pm UTC](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/61 "2020-09-11T13:03:00Z")
While `and` is ambiguous, I’m pretty sure that of you asked any Julia coder to read a line with `&&` in it, they would pronounce it “and”.
[Previous page](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263.md?page=2)
[Next page](https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263.md?page=4)