Julia: add docstrings for `and` and `or`

[StefanKarpinski]

https://discourse.julialang.org/t/and-or-bitwise-or-shortcircuit-what-we-get-searching-docs/46263/25

Since people coming from some languages expect and and or to be keywords, we could add docstrings for these as keywords so that ?and and ?or in the REPL give help strings indicating that the correct short-circuit boolean operators in Julia are && and ||.

[Moelf]

can you show an example where we document non-existing stuff? I can work on this

[simeonschaub]

You probably want to add it here: https://github.com/JuliaLang/julia/blob/master/base/docs/basedocs.jl

[tpapp]

Generally I don't think we should be adding documentation for syntax in other languages, there is just too much of it. Once we do this, it is reasonable to ask that ( mentions [ (Matlab), etc.

Specifically, AFAICT Python is the outlier with using and and or among modern programing languages. Pretty much everyone else uses && and ||, including C/C++, Matlab, R. We should mention this difference in the Python section of Noteworthy differences....

[henriquebecker91]

@tpapp Note this is just incidentally documentation for syntax in other languages, and and or are the pronounceable names of the operators, words people associate with them, and search them by. We do not even need to mention Python (or any other language) in such entries.

Nothing against also mentioning them in the aforementioned section of the manual.

[tpapp]

@henriquebecker91: asking the same question I asked on discourse: if

this is just incidentally documentation for syntax in other languages, and and or are the pronounceable names of the operators, words people associate with them

then should ?plus take you to the docstring for +? Is this something we really want to do? If not, can you explain why not?

Also, currently ? looks up docstrings for symbols, and does not do search. That's what eg apropos is for.

Incidentally, apropos("boolean and") (or even "boolean") does not turn up && or ||. I think that simply fixing that would be enough.

[Moelf]

I think to have ?and and, say, not ?plus is due to the same reason why we mention "Significant difference from C++/Python/MATLAB" but not, for example, Java/JavaScript/C# -- we have some ~ target audience / popular language switching target here. (this is only my personal take)

[simeonschaub]

I must admit that I rarely found apropos to be particularly useful, especially for common words like this. apropos("and") just turns up basically everything and I would argue that users that have heard of "boolean logic" before, have probably also seen code in other languages that use || and &&, so I don't think a lot of people looking for this would know to search for apropos("boolean and").

[henriquebecker91]

I like @Moelf take. 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.

[henriquebecker91]

And, the same target audience for this improvement will be the people that know about ? but not about apropos.

[stevengj]

On a related note, I added some clarification to the manual in #37489.

[tpapp]

&& and || are much more arbitrary symbols (specially the fact they are doubled and not just & and |) and not shared by all programming languages while

Not all, but most languages use these symbols nowadays, especially in the niche Julia targets (again, Python is an exception).

While I recognize that these operators are new for some people, I am not convinced that

1. this problem is very common (again, those other languages do just fine with these operators),
2. the docstrings are the best place to address this (as opposed to a clarification like #37489)
3. the manual/docstrings should be going in this direction (explained below).

I don't feel very strongly about this particular operator, but I am concerned about the following pattern:

1. a new Julia user who does not read (or even skim) through the manual runs into an issue about something that is actually documented.
2. they blame the manual/docstrings, and ask for/contribute an addition that clarifies this.
3. the manual and the docstrings get ever longer with redundant information, so
4. even fewer people read through them.

I don't doubt that everyone means well, but I think that this is a vicious cycle.

I propose the following to remedy this:

1. Generally, if something is documented in the relevant section, that should be sufficient. Cross-references to this section should be encouraged, but not repetition.
2. Conceptual clarifications and examples are great, but the docs should not be turned into an incarnation of Clippy ("did you mean...?", cf #37496)
3. Core devs should clarify what the manual and the docstrings are for as a general guideline (define the API, introduce techniques very specific to Julia, or teach general programming concepts?)
4. editorial PRs that consolidate and rework parts of the manual should be encouraged.

[PallHaraldsson]

I think that this is a vicious cycle.

All of us here know what e.g. || does (and doesn't do, string concatenation) or * vs. +, so the REPL help isn't for us. I think simply documenting a bit more would help beginners, and avoid discussions on discourse, so I would opt to document a bit more, not less "on the safe side".

[henriquebecker91]

but I think that this is a vicious cycle.

And I think this is a slippery slope.

I am arguing in favor of including ?and and ?or, not of any changes in the manual, keep this in mind.

You say that "I am not convinced that [...] the docstrings are the best place to address this (as opposed to a clarification like #37489)". You do not further discuss why they would not be the best place to address this, nor why the clarification of #37489 replaces the dosctrings instead of complementing them.
You say that "I am not convinced that [...] the manual/docstrings should be going in this direction" but the only negative outcome you arrive is that "even fewer people read through them".

I do not believe the docstrings were created with the purpose of being exhaustively read. The purpose of a reference (different from a manual) is to be queried on demand, to elucidate specific points the user is confused about. The docstrings are not automatically added to the manual. And, to my knowledge, there is no easy way of just listing all of them to read them exhaustively. Someone doing that is already going out of their way to do so.

While I think your argument makes some sense when applied to the manual, I fail to see how it applies to the docstrings, and this left me unconvinced. Seems to me you are just repeating an argument you already made many times before, without adjusting to what I am actually saying.