The computer's not gone yet, and I felt like listing one more thing that's been on my mind. I think a language feature can be removed, and fewer features is usually better in my book.

Instead of this:

**
** This method is the coolest.
** You should call it every day.
**
Void coolThang() {
  // ...
}

Can we say this?

@doc =
 "This method is the coolest.
  You should call it every day."
Void coolThang() {
  // ...
}

The string syntax is lighter weight for reading, a feature gets removed from the language, and you already have a facet API for reading the docs at runtime. Is it a win?

Looks really cool, actually.

In addition, it would serve as a constant reminder about the magic indent space stripping of the compiler...

I'm rather fond of the ** comments. I think the stars are pretty! I also like how they line up nicely, compared to the offsides quote and "@doc =".

From a more practical standpoint, fandocs don't require escaping quotes. I think fandoc comments are an appropriate place for short code examples, and those examples could easily contain quotes, requiring you to mentally unescape them.

But if fandoc was implemented as a shorthand for your @doc facet, that wouldn't be too bar, I suppose.

Thats interesting, but I think we need to stick with using **. It reads much better, and makes it much easier to generate proper fandoc (this dovetails into the multi-line string debate).

Yeah, I agree. Although it would be nice to eventually compile this in, so you could look up documentation without having source code. Often I've wanted that feature.

You can get the fandoc from compiled code using Type.doc and Slot.doc.

That's an awesome feature! Nothing more is needed.

Cool! I almost fell of my chair laughing with glee.

Of course the next question is whether the source code is available at runtime?!!

If you explicitly build it then the source code is included in the pod file. Here's the code from docCompiler:

srcFileFacet := t->sourceFile
srcFile := t.pod.files["/src/$srcFileFacet".toUri]

I find it interesting that this:

text :=
  "More than one line
   in this text."

Reads better than this:

text :=
  "More than one line
  "in this text.

But this:

**
** More than one line
** in this text.
**

Reads better than this:

text :=
  "More than one line
   in this text."

I guess it's the context. Anyway, I'm fine going with others on this one. Just wanted to throw it out there.

I don't like the Python style, and I love the ** style - so not likely to change.

They look good (personal opinion of course), and are easy to color code in pretty much any editor.

Using a string literal creates all sorts of nightmares with regard to escaping characters, which is bad in comments that contain code examples (although triple quoted strings could help solve that somewhat).