The difference between Ceylon and Scala

ceylon-vs-scala

// the difference between ceylon and scala
//

shared
class Polar(Float angle, Float radius) {
    shared
    Float angle = angle;

    shared 
    Float radius = radius;
}

class Polar(val angle: Float, val radius: Float)

Now what do the two examples look like when you add javadoc to Polar, angle, and radius?

/**
 * ...
 */
by "foo"
shared
class Polar(Float angle, Float radius) {
    /**
     * ...
     */
    shared
    Float angle = angle;

   /**
     * ...
     */
    shared 
    Float radius = radius;
}

/**
 * ...
 * @author foo
 */
class Polar(
  /**
   * ...
   */
  val angle: Float,

  /**
   * ...
   */
  val radius: Float)

The Ceylon example is wrong. Use doc "..."

doc "..."
by "foo"
shared class Polar(Float angle, Float radius) {
    doc "..."
    shared Float angle = angle;

    doc "..."
    shared Float radius = radius;
}

One could now argue about whether or not an annotation clarifies as a comment but okay. I can add @doc to Scala or write /** ... */ for single-line comments if that makes you happy.

The point of the Gist is the verbosity of an every day task. And you try to change the subject :)

One could now argue about whether or not an annotation clarifies as a comment

There's nothing to argue: that's simply how you write "javadoc" in Ceylon.

The point of the Gist is the verbosity of an every day task.

Well, of one particular cherry-picked example, at least.

And you try to change the subject :)

I'm not trying to change the subject, rather I'm trying to demonstrate why I'm resisting supporting the following in Ceylon:

shared class Polar(shared Float angle, shared Float radius) {}

Now, this would be a rather trivial change to the language, and some of the team (especially Tako) are very much in favor of doing it. My argument is that this syntax doesn't scale very well once you start adding documentation and annotations. (Annotations and documentation on parameters usually look ugly to my eyes.) And furthermore, it's something we can decide to support at any time if there is real community demand for it (on the other hand it's something that would be difficult to remove later). So, even though I will very likely end up losing this argument, I want us to make this decision as a community, once everyone has really thought through the tradeoffs.

So how would a full example of a real world comment look like?

doc "The Polar class [...].

<p>Here we explain some more</p>

<p>The angle is defined in radians. Use {@link java.lang.Math#PI} etc. Wait how do I write an inline link? I need another documentation syntax plus the annotations. Cool.</p>

This is going to be a lot of fun if I have to write all my code examples in a string literal and things like \t or other characters become magically transformed.
"
see(Math.PI) // wait, this should say "see(3.14...)" so is see a special annotation which does not evaluate constants?
by "foo"
shared // that other guy added the param annotations later in the code so we are left with shared here
param("angle", "Is this how I annotate a parameter? See see(Radians) ??? for conversion to radians.")
param("radius", "The radius")
by "that other guy" // that other guy added himself as another author
class Polar(Float angle, Float radius) {

    doc "The angle in radians
<p>We add some more documentation. The code looks even uglier now because
I do not want to have spaces in front of my documentation string so I may not indent
anything or cannot make use of a multi-line string literal</p>
<p>Just imagine I have an example and a &lt;pre&gt; element..."
    shared 
     Float angle = angle;

    doc "The radius.
<p>Can be positive or negative.</p>
<p>If the radius is negative the resulting coordinate will be in the opposite quadrant of @link{#angle} or however you link in between.</p>"
    shared 
    Float radius = radius;
}

I guess the point is that in many cases like prototyping, working with the REPL, ... there is no need for documentation, it is even counterproductive. Has anyone ever seen a REPL session with documentation in it? There is just no demand for it.

In the end, it is a question of being pragmatic and a matter of taste. Sure, no one will prevent anyone wishing for Java's verbosity to use Ceylon.

So how would a full example of a real world comment look like?

Not exactly. Ceylon doc annotations support embedded Markdown, which is much easier on the eyes than HTML comments.

We add some more documentation. The code looks even uglier now because
I do not want to have spaces in front of my documentation string so I may not
indent anything or cannot make use of a multi-line string literal

Of course you can indent the doc. Not even sure why you would think you can't....

P.S. Not going to respond to the rest of your post, since it looks to me like you're inventing problems rather than trying to imagine solutions. Come back to me when you've actually written some code in Ceylon and have run into actual problems.

I guess the point is that in many cases like prototyping, working with the REPL

REPL is nice, and like I said above, it's likely that I will end up losing this argument, and we will end up supporting this syntax, but on the other hand, I don't think it's right to design a whole general purpose language around what's convenient in a REPL.

Prototyping, REPL, scripting, ... the list is quite long.

But besides of the HTML/Markdown/... syntax, won't you need something special to refer to a constant or fields? How do you expect see(Math.PI) to work?

The indentation is about spaces at the beginning of a line and this is quite annoying if my code examples are indented.

See

doc "Comment
     Here we try to make it look nice by indenting some text.
     <pre>
     if(x) {
       // I would like to see only 2 spaces of indentation here.
     }
     </pre>"
class X {
  doc "Comment
       Here I have a lot of spaces.  If this would be a code example it could look shifted to the right.
       But since we are at a different indentation level the code example would be shifted even more
       to the right."    
  T y;
}

vs.

class X {
  doc "Comment
No white-space here."
  T y;
}

It is not about can vs. can't but it sure will look different if you would think of a < p r e > environment.

Prototyping, REPL, scripting, ... the list is quite long.

If enough of our community feels the same, trust me, I'll happily fold on this one. We're trying to produce something that people will enjoy using, not shove one person's preferences down everyone else's throat.

But besides of the HTML/Markdown/... syntax, won't you need something special to
refer to a constant or fields? How do you expect see(Math.PI) to work?

Sure, that's the purpose of Ceylon's typesafe metamodel. We'll have typesafe method/attribute references built into the language (but not in M1).

It is not about can vs. can't but it sure will look different if you would think of a < p r e >
environment.
...
The indentation is about spaces at the beginning of a line and this is quite annoying if
my code examples are indented.

Sure. My intended solution is simply to strip off the indent before passing the text to Markdown. I don't see this causing any problems. (Note we have not yet implemented it, however.)