short-circuit operators not shown as by-name

[scabug]

The Scaladoc for Boolean.&& and Boolean.|| does not list the arguments as by-name (=>).

[scabug]

Imported From: https://issues.scala-lang.org/browse/SI-143?orig=1
Reporter: @lexspoon

[scabug]

@dubochet said:
By-name arguments are printed correctly in Scaladoc 2.

[SethTisue]

&& doesn't show up as having a by-name argument at either https://www.scala-lang.org/api/2.13.12/scala/Boolean.html or https://www.scala-lang.org/api/3.3.1/scala/Boolean.html

This came up on Discord today

I don't doubt this has been handled correctly for by-name methods in general since some now-antique Scala version, but the original report was about && and || in particular

these methods are compiler fictions, I think, and it looks like the fiction needs adjusting

[som-snytt]

Spec at https://scala-lang.org/files/archive/spec/2.13/12-the-scala-standard-library.html#class-boolean

The Scaladoc has a "note" about the actual behavior.

The problem is not casual:

scala> def f(x: => Boolean) = 42
def f(x: => Boolean): Int

scala> val g = f _
val g: (=> Boolean) => Int = $Lambda/0x00007fb988483618@d13960e

scala> g(???)
val res0: Int = 42

scala> val g = true.|| _
val g: Boolean => Boolean = $Lambda/0x00007fb9884850f0@49653791

scala> g(???)
scala.NotImplementedError: an implementation is missing
  at scala.Predef$.$qmark$qmark$qmark(Predef.scala:344)
  ... 30 elided

Maybe Scala 3 will be more precise. But I guess I don't know how inline works yet:

scala> inline def f(inline x: => Boolean) = 42
def f(x: => Boolean): Int

scala> val g = f _
1 warning found
-- Warning: ------------------------------------------------------------------------------------------------------------
1 |val g = f _
  |        ^^^
  |        The syntax `<function> _` is no longer supported;
  |        you can simply leave out the trailing ` _`
val g: (=> Boolean) => Int = Lambda/0x00007f3fe851c000@120d6cbf

scala> g(???)
scala.NotImplementedError: an implementation is missing
  at scala.Predef$.$qmark$qmark$qmark(Predef.scala:344)
  ... 33 elided

[lexspoon]

these methods are compiler fictions, I think, and it looks like the fiction needs adjusting

What an old ticket! While I can't remember my thinking from back then, I think I agree with the quoted text here--update the doc to show the fiction a little better.

Based on the link to the spec, the spec is using the => Boolean type. Thus, the Scaladoc output currently disagrees with the language spec.

The way the spec has it makes good sense to me. If it's a compiler fiction anyway, why not tell a simple story that teaches a little about Scala. The by-need parameter syntax is Scala's answer to short-circuiting. Unlike in Java, you can define your own methods that act like && and ||. How strange if, for the actual && and || methods, Scaladoc takes a different way to explain it.

By the way, those code samples look like bugs of their own that probably deserve a new ticket. You shouldn't be able to compile something so simple and still get a NotImplementedError.

[Ichoran]

Now that we have inline, which is an honest description of what is happening, maybe the docs should say that? The by-name annotation, in a context where by-name annotations necessarily mean the creation of a 0-arg function option, doesn't seem particularly more helpful to me than a description stating that the argument is short-circuited.

In contrast, inline def &&(inline b: Boolean) = if a then true else b is exactly what's happening.