"and", "or", bitwise or shortcircuit, what we get searching docs

[tomerarnon]

@Tamas_Papp

apropos

Wow! I did not know about this, and it’s incredible that this exists!

[lmiq]

@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.

[devel-chm]

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.

[Henrique_Becker]

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).

[Oscar_Smith]

I think it would be good to for example link inv to \. Common words and punctuation are really hard to search

[opera_malenky]

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, it shows results for millions of function definitions from base and stdlib, which makes the search pretty useless for me.

[kevbonham]

@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

[lmiq]

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 ||.

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.

help?> &&
search: &&

  x && y

  Short-circuiting boolean AND.

[Palli]

@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).

[simeonschaub]

I appreciate your effort, but did you follow the discussion in 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.

[Tamas_Papp]

@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 argument. Sorry for the misunderstanding, I did not expect that someone would actually do it.

[stevengj]

@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

[Henrique_Becker]

@Tamas_Papp

That was meant as a reductio ad absurdum argument.

This hardly qualify as a reduction ad absurdum. You used a slippery slope argument, 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.

[Tamas_Papp]

@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.

[Henrique_Becker]

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).

[Tamas_Papp]

@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.

[Tamas_Papp]

Opened an issue:

https://github.com/JuliaLang/julia/issues/37523

[tomerarnon]

@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> 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.

[Tamas_Papp]

Yes, that should be fixed.

[Oscar_Smith]

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”.