Missing documentation for ? operator, and how to improve documentation

Hi there

I overall like the Julia documentation. It’s more comprehensive than most languages, and still, it lacks some things.

I am new to Julia, and found an example, that attempts to showcase multiple dispatch.
A part of the code is this:

collide(x::SpaceObject, y::SpaceObject) = (x.size > 100 && y.size > 100) ? "Big boom!" : collide_with(x, y)

So, me not knowing what ‘?’ is supposed to mean, I hover over the item with my cursor.
The VS Code extension doesn’t like to say me anything, so there could we improve something.
And then, looking up for “operators” or simply “?” directly yields me nothing in the documentation.

I really looked for 15 minutes, there is nothing. At least not something, that I could find.
I also suggest, to provide an overview of ALL operators on one page, or some kind of cheat sheet.

Can you explain me, what this operator does, and how we can improve the documentation?
An info box in VS Code would be by far the best thing.

Congratulations to the docs otherwise, they are overall really good.

2 Likes

Typing ? in the REPL to go to help mode, and then ? as the object to get help on, gives details on the operator with examples:

help output
help?> ?
search: ? ?:

  a ? b : c

  Short form for conditionals; read "if a, evaluate b otherwise evaluate c". Also known as the ternary operator
  (https://en.wikipedia.org/wiki/%3F:).

  This syntax is equivalent to if a; b else c end, but is often used to emphasize the value b-or-c which is being used as part of a
  larger expression, rather than the side effects that evaluating b or c may have.

  See the manual section on control flow for more details.

  Examples
  ≡≡≡≡≡≡≡≡≡≡

  julia> x = 1; y = 2;
  
  julia> x > y ? println("x is larger") : println("y is larger")
  y is larger

Not sure how VS Code picks up docs or why it doesn’t work for this case.

6 Likes

I do agree with the idea of an overview page listing all the operators. When I was a Perl developer, the special perldoc pages like perldoc perlre (for RegEx), perldoc perlop (for operators), etc. were very useful, a quick and easy reference for comprehensive info.

The Julia manual has a page for mathematical operators, but to find ? : you’d have to go to the Control Flow page which you couldn’t guess if you didn’t know what the operator does in the first place.

3 Likes

Oh, that is very helpful

I did create an issue.

Yeah, particularly since that topic doesn’t contain the word ‘operator’, so my search did not yield it.

So, an overview page for all operators would duplicate the information.
I would be more for a cheat sheet, since I see many more benefits in such one.

Any ideas, what to add for that one?
Thanks

I usually start with the Ask AI in Julia hub. This is what it gave for “what does the ? operator do”. Which is ironic because it couldn’t find the documentation either.

Based on the provided context, it seems that the “?” operator is not explicitly mentioned in the documentation of the Julia packages mentioned. However, in Julia, the “?” operator is not a built-in operator with a specific meaning.

In general, the “?” character is often used in programming languages as part of a ternary operator, which is a shorthand way of writing an if-else statement. The ternary operator takes the form: condition ? expression_if_true : expression_if_false. It evaluates the condition and returns the value of the expression_if_true if the condition is true, otherwise it returns the value of the expression_if_false.

For example, in Julia, you can use the ternary operator to assign a value based on a condition:

x = 5
y = x > 0 ? "positive" : "negative"
println(y)  # Output: "positive"

In this example, if the condition x > 0 is true, the value of y will be assigned as “positive”, otherwise it will be assigned as “negative”.

It’s worth noting that the usage of the “?” operator may vary depending on the specific package or context in which it is used. Therefore, it is recommended to consult the documentation of the specific package or library you are working with to understand the exact meaning and usage of the “?” operator in that context.

1 Like

Thats even far better.

I wonder if that AI could just write our documentation for us :stuck_out_tongue:

This page is also quite helpful, the ternary operator appears here.

https://docs.julialang.org/en/v1/base/punctuation/#man-punctuation

3 Likes

There is this cheat sheet, in which ? is mentioned (both as the ternary operator and the way to enter the help> REPL mode). I think such cheat sheets are indeed useful, especially for newcomers.

https://cheatsheet.juliadocs.org/

2 Likes

Could we maybe place them a little more prominent?

This is wrong.

Also wrong. (? is a keyword, and not a function call like ordinary operators, and its behavior can’t be modified/overloaded by packages.)

See ? in the manual and the control flow section of the manual’s discussion of the ternary operator.

Sure, if we want the documentation to be confidently wrong…

See also the discussion in chatGPT policy needed? … ML-generated answers often do more harm than good.

4 Likes

Sorry, to clarify I was only suggesting juliahub as a tool to try out when you can’t find it vscode extension and in this case you were struggling for 15 minutes.

Ideally having the information more easily in the vscode extension directly would be better. Thank you for the cheatsheet link.

1 Like

Can I guess about why this is the case? I assume because it is the only operator, that applies to three different elements?

I dont know, it just seems like an obvious difference to all the others, and so I assumed, this might be related? Or why is this implemented differently?

True. On a more serious note, I assume it might be nice as a template, that is then edited, plus obviously double-checked, before committed.

The answer above has surely added more useful information to me personally, than any of the documented info did before. So I definitely see some value in it, although I am well aware, that we can’t let them write all the docu unchecked. Hence, the tongue-showing smiley :wink:

No, it’s just a short-hand syntax for the longer-form if/else version. In fact it parses identically:

julia> Meta.parse("t ? x : y")
:(if t
      x
  else
      y
  end)
3 Likes

I made it to my personal policy, that I always look for a solution that benefits everyone, particularly newbies.

I appreciate the tip with the JuliaHub.

And still, I could not sleep, knowing that I solved the issue for myself, just that the next newbie would run into it.

That would appear rather egocentric to me personally. I know how hard it is as a newbie, so I care about that experience for others.

Thanks again for your help, greatly appreciated. :+1: :wink:

And that couldn’t have been expressed as a function? Or why is it implemented differently. :slight_smile:

A related functionality is available as a function: ifelse — and its docs tell you why it’s different:

This differs from ? or if in that it is an ordinary function, so all the arguments are evaluated first.

Control flow changes what gets executed. See, for example the difference between:

julia> false ? println("hello") : nothing

julia> ifelse(false, println("hello"), nothing)
hello
7 Likes