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)

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