scaladoc 2 convention on indenting scaladoc comments

[Stuart Roebuck]

Recently the IntelliJ plugin for Scala has started to enforce the scaladoc 2 convention of comments in the form:

  \** Start the comment here

    * two spaces before the asterisk on following lines

    * and the last line ending at the end like this */

Prior to this it stuck with the convention being used throughout the Scala codebase and documented in the Scala Style Guide here: http://davetron5000.github.com/scala-style/scaladoc/index.html.

Why is scaladoc 2 pushing a change to a convention that has happily existed without problem for such a long time?

It is not clear that there is any need to make this change in order to implement any of the additional scaladoc 2 functionality which is undoubtedly a good thing.

I raised this as a ticket here: https://lampsvn.epfl.ch/trac/scala/ticket/4555 but have been asked to move it to this list.

[martin odersky]

I am as mystified as you are. None of that was ever discussed, as far as I recall. And you are right that the recommendation is in disagreement with essentially all published Scala sources, as well as most standard formatters including those for Emacs and Eclipse.

If we do not hear convincing arguments for the change we should change the recommendation back.

Cheers

 -- Martin

--
----------------------------------------------
Martin Odersky
Prof., EPFL and CEO, Scala Solutions
PSED, 1015 Lausanne, Switzerland

[Rüdiger Keller]

I don't really like the new style. And I see no reason to enforce a
new style when nothing is wrong with the old style.

For me the new style lacks visual hints of where the comment starts
and ends and I feel the "old" Javadoc style does quite well in that
regard.

Regards,
Rüdiger

2011/5/9 Stuart Roebuck <stuart....@gmail.com>:

[Alois Cochard]

Same for me, really don't like the new style.

And I must admit that I don't see any advantage of using this new style ?

[Lukas Rytz]

I was also very surprised to see that today.

Until seeing this message I thought it was a bug in IntelliJ.

[Johannes Rudolph]

If I understand Simon's comment from the ticket, the problem is, that
the Scaladoc markup language (the 'wiki syntax') relies on indentation
to be correct. And this can be hard to get right if it isn't clear
what the left border of your text actually is.

I don't see why closing the comment on the last line is recommended, though.

--
Johannes

-----------------------------------------------
Johannes Rudolph
http://virtual-void.net

[Rex Kerr]

Surely someone can write a few lines of code that figure out where the left border is.  Something like

    val validDoc = """(\s+\*\s*\S.)"""r
    val doccable = lines.flatMap(s = validDoc.findPrefixMatchOf(s).map(_.end-2))
    val left = if (doccable.isEmpty) 0 else doccable.min
    lines.map(_.substring(left))

--Rex

[martin odersky]

On Mon, May 9, 2011 at 5:01 PM, Rex Kerr <ich...@gmail.com> wrote:

Surely someone can write a few lines of code that figure out where the left border is.  Something like

    val validDoc = """(\s+\*\s*\S.)"""r
    val doccable = lines.flatMap(s = validDoc.findPrefixMatchOf(s).map(_.end-2))
    val left = if (doccable.isEmpty) 0 else doccable.min
    lines.map(_.substring(left))

As far as I know, that's already done.

 -- Martin

[Rüdiger Keller]

2011/5/9 Johannes Rudolph <johannes...@googlemail.com>:

> If I understand Simon's comment from the ticket, the problem is, that
> the Scaladoc markup language (the 'wiki syntax') relies on indentation
> to be correct. And this can be hard to get right if it isn't clear
> what the left border of your text actually is.

I don't see the problem here. Why should it be a problem to determine
where the left border is? Unless you begin your comment in the first
line starting with /** there are no ambiguities. And beginning in the
first line would be against the conventions if I'm not mistaken.

Sure, there is some rather involved regex code for handling the left
border in the current Scaladoc implementation, but that isn't affected
by the new style as far as I remember.

Regards,
Rüdiger

[Jason Zaugg]

I think the intended benefit is for human-, rather than machine-, parseability.

-jason

[Rüdiger Keller]

Ok, I see. I didn't consider this, because it never occurred to me to
use the first line of a comment for text. I guess this depends on
background and habits...

Regards,
Rüdiger

2011/5/9 Jason Zaugg <jza...@gmail.com>:

[Johannes Rudolph]

On Mon, May 9, 2011 at 5:16 PM, Rüdiger Keller
<ruedige...@googlemail.com> wrote:
> I don't see the problem here. Why should it be a problem to determine
> where the left border is?

Of course, you can determine the left border automatically in the
compiler if you assume some convention of where the left border is. If
you look at the Scaladoc comments as they are now in the library this
convention seems to be - at places - non-obvious [1]. Compare that
with the new convention where this question doesn't even arise. This
is more about visual clarity than implementation.

This said, I don't really prefer one way over the other, however,
having to move a complete code base to a new comment scheme to appease
the IDE doesn't seem to be the right way.

--
Johannes

[1] It seems to be something along: The first line starts one blank
after **, the next lines need two blanks to be aligned with the first
and if you use the <pre>-tag it uses only one blank so that the inner
code is aligned.

[Simon Ochsenreither]

Hi everyone,

>>> If I understand Simon's comment from the ticket, the problem is, that
>>> the Scaladoc markup language (the 'wiki syntax') relies on indentation
>>> to be correct. And this can be hard to get right if it isn't clear
>>> what the left border of your text actually is.

> I think the intended benefit is for human-, rather than machine-, parseability.

Exactly. It is just not intuitive at all with the old style.

It doesn't matter in JavaDoc, but with the WikiSyntax it wastes a lot of
time, if one sees after half an hour that ScalaDoc actually had a
different interpretation of what the right indentation should be.

I think there were good reasons when it changed in 2.8 and back-pedaling
on it just because the IDEs don't support Scala as fast as we all would
like to see it and some people didn't read the documentation, is really
a shame.

Maybe someone should ask the original authors for comments?

Imho the current style is an improvement over the old one, especially
from a human-readability POV and as someone who actually writes
documentation a lot I really like it, although it took some time to
acclimate with it.

Personally I would prefer it to actually work on the 70% of ScalaDoc
which are not implemented yet (despite claims in the wiki), instead of
ripping apart the pieces which actually started to work recently.

Thanks and bye!

Simon

[Jason Zaugg]

On Mon, May 9, 2011 at 5:31 PM, Johannes Rudolph
<johannes...@googlemail.com> wrote:
> This said, I don't really prefer one way over the other, however,
> having to move a complete code base to a new comment scheme to appease
> the IDE doesn't seem to be the right way.

It's supported, not enforced, in IntelliJ. We'll review the default
setting based on this thread.

To revert to the old style, Settings, Code Style, Spaces, Scala, "Use
formatting for ScalaDoc2 options".

-jason

[Rüdiger Keller]

Ok, it seems that leaving the first line of a Scaladoc comment empty
is not something appreciated by many Scala coders.

I remember seeing some "strangely" formatted comments in the Scaladoc
code. Thinking back now, it was probably following the new proposed
convention.

Nevertheless, if I remember the code correctly the Scaladoc tool
assumes that the border of a comment is everything up to and including
the first * and then one additional whitespace if there is some. For
the first line, it's everything up to and including the /** and also
one additional whitespace. So if you have one whitespace in the first
line and two in the following lines to align them, you end up with
differing indentations as far as Scaladoc is concerned...

Personally I would prefer the classical Javadoc style with an empty
first line, but to each his own.

Regards,
Rüdiger

2011/5/9 Johannes Rudolph <johannes...@googlemail.com>:

[martin odersky]

On Mon, May 9, 2011 at 5:43 PM, Simon Ochsenreither <si...@ochsenreither.de> wrote:

Hi everyone,

If I understand Simon's comment from the ticket, the problem is, that
the Scaladoc markup language (the 'wiki syntax') relies on indentation
to be correct. And this can be hard to get right if it isn't clear
what the left border of your text actually is.

I think the intended benefit is for human-, rather than machine-, parseability.

Exactly. It is just not intuitive at all with the old style.

It doesn't matter in JavaDoc, but with the WikiSyntax it wastes a lot of time, if one sees after half an hour that ScalaDoc actually had a different interpretation of what the right indentation should be.

I think that's backwards. If ScalaDoc cannot deal with the standard convention it needs to be fixed. If you know it does not work, can you please file a ticket? And I mean that independently of how the style discussion pans out. Clearly scaladoc's functioning should not be dependent on a particular style.

Cheers

 -- Martin

[Stuart Roebuck]

Jason,

Thanks for pointing out that settings option.  I confess that I searched a lot but didn't find it until you pointed it out here.

Stuart.

[Simon Ochsenreither]

Hi!

> I think that's backwards. If ScalaDoc cannot deal with the standard
> convention it needs to be fixed. If you know it does not work, can you
> please file a ticket? And I mean that independently of how the style
> discussion pans out. Clearly scaladoc's functioning should not be
> dependent on a particular style.
>

I don't think that there is a solution with the old format. Consider for
example an unordered list starting at the first line.

Either I don't have the text aligned, which just looks horrible and is
counterintuitive, because it ends up on the same level in HTML.

Or I align the text, and now my list has actually a sublist in it as a
result, while it looks totally innocent in the source code.

Maybe I'm exaggerating a bit, but I think it is either going back to the
old style and using html tags again or going with the new style and
using trac style (although I'm not really sure if it obsoletes all use
cases of html currently, especially in code examples + formatting).

I have just seen too much mis-formatted ScalaDoc in the last few weeks
while fixing the old TeX-style quotes, and I think the current style of
same-indentation-everywhere might reduce some of the most common errors.

I just wonder, if we pack-pedal that thing, will we back-pedal for
instance on the matter of TeX-style quotes, too, just because not many
people care that it is totally unsupported and breaks the formatting
everywhere in ScalaDoc2?

Thanks and bye,

Simon

[martin odersky]

On Mon, May 9, 2011 at 5:59 PM, Simon Ochsenreither <si...@ochsenreither.de> wrote:

Hi!

I think that's backwards. If ScalaDoc cannot deal with the standard convention it needs to be fixed. If you know it does not work, can you please file a ticket? And I mean that independently of how the style discussion pans out. Clearly scaladoc's functioning should not be dependent on a particular style.

I don't think that there is a solution with the old format. Consider for example an unordered list starting at the first line.

Either I don't have the text aligned, which just looks horrible and is counterintuitive, because it ends up on the same level in HTML.

Or I align the text, and now my list has actually a sublist in it as a result, while it looks totally innocent in the source code.

Does anyone actually do that? Scaladoc with an unordered list at the first line? What kind of meaningful doc comment would start with an unordered list?

I'd say, if people do that, they'd deserve any random behavior of the tool.

 -- Martin

[Jason Zaugg]

On Mon, May 9, 2011 at 5:59 PM, Simon Ochsenreither
<si...@ochsenreither.de> wrote:
> Hi!
>
>> I think that's backwards. If ScalaDoc cannot deal with the standard
>> convention it needs to be fixed. If you know it does not work, can you
>> please file a ticket? And I mean that independently of how the style
>> discussion pans out. Clearly scaladoc's functioning should not be dependent
>> on a particular style.
>>
>
> I don't think that there is a solution with the old format. Consider for
> example an unordered list starting at the first line.

How often does that come up? Did you find this in the comments for
scalac or the standard library?

-jason

[Simon Ochsenreither]

Hi,

> Does anyone actually do that? Scaladoc with an unordered list at the
> first line? What kind of meaningful doc comment would start with an
> unordered list?

It was just one example where ScalaDoc behaves inconsistent. The whole
tool is full of these quirks and it is quite hard to remember all of
them while writing documentation.

It would be nice to reduce the complexity of writing documentation and I
think the current comment style does that, while also reducing the
visual clutter and making the appearance in the source code similar with
the appearance in HTML.

> I'd say, if people do that, they'd deserve any random behavior of the
> tool.

Yes, sure. But abusing tools often shows the weaknesses they have more
clearly. :-)

There is just so much work left on ScalaDoc, implementation-wise _and_
specification-wise, and hope this discussion about comment style won't
waste time with things which should be considered fixed.

Maybe there should be more attention spent on IDE plugins instead so
that the recommended style is implemented with less delay. (So that
people can see it and complain in a timely manner and not 2 releases
later :-D)

Thanks and bye,

Simon

[Stuart Roebuck]

It does feel like a solution looking for a problem and causing one!

The vast majority of code is of the form:

/**

 * COMMENTS GO HERE

 * AND HERE

 * ETC

 */

or occasionally:

/** A SHORT COMMENT */

That is the standard convention and a perfect clear and unambiguous one to maintain compatibility with as well as, by all means, with the new:

/** COMMENTS GO HERE

  * AND HERE

  * ETC */

format as well.

Edge cases that don't conform to the above just need to be handled consistently with some documented algorithm so that developers who like to be different can understand why their comments are broken.  Personally I think the left margin should simply be defined as "* " which is at least simple and consistent with the Scala stripMargin approach to handling left margins.

Stuart.

P.S. I think ScalaDoc 2 and the new HTML rendering is great.  That's why this matters! :)

[Simon Ochsenreither]

Hi!

> How often does that come up? Did you find this in the comments for
> scalac or the standard library?

I found most of the various quirks while working on that
https://github.com/soc/scala/commit/2fb4fce55ca81722c8f1cfcc8f81cc9ce7414f33
commit, but I frankly don't remember the specific file anymore.

It is just that I'm grateful for any actual reduction of complexity
after I tried to make some fixes to the library. I believe there is
something wrong when even the gods of higher-kinded types and implicits
sometimes don't understand ScalaDoc correctly. :-)

Thanks and bye,

Simon

[Chris Twiner]

I too prefer an empty first line and end line. I find the op example unpleasant to read.

On 9 May 2011 17:49, "Rüdiger Keller" <ruedige...@googlemail.com> wrote:

Ok, it seems that leaving the first line of a Scaladoc comment empty
is not something appreciated by many Scala coders.

I remember seeing some "strangely" formatted comments in the Scaladoc
code. Thinking back now, it was probably following the new proposed
convention.

Nevertheless, if I remember the code correctly the Scaladoc tool
assumes that the border of a comment is everything up to and including
the first * and then one additional whitespace if there is some. For
the first line, it's everything up to and including the /** and also
one additional whitespace. So if you have one whitespace in the first
line and two in the following lines to align them, you end up with
differing indentations as far as Scaladoc is concerned...

Personally I would prefer the classical Javadoc style with an empty
first line, but to each his own.

Regards,
Rüdiger

2011/5/9 Johannes Rudolph <johannes...@googlemail.com>:

> On Mon, May 9, 2011 at 5:16 PM, Rüdiger Keller
> <ruedige...@googlemail.com> wrote:

>> I don'...

[Simon Ochsenreither]

Hi,

let's not start a flame war. :-)

It does feel like a solution looking for a problem and causing one!

Maybe the change back in Scala 2.8 was debatable, but back-pedaling now is just worse, especially if the change itself was an improvement.

I think that such changes could be better announced publicly and implemented with less delay in the tooling.

But really, I think reversing a change _after_ tooling finally started to support it, is just a bad move.

Edge cases that don't conform to the above just need to be handled consistently with some documented algorithm so that developers who like to be different can understand why their comments are broken.  Personally I think the left margin should simply be defined as "* " which is at least simple and consistent with the Scala stripMargin approach to handling left margins.

I agree. The current approach does exactly that and actually also looks like that in the source code, because everything lines up consistently.

P.S. I think ScalaDoc 2 and the new HTML rendering is great.  That's why this matters! :)

I just feel with the same argument we could also throw away the new ScalaDoc, because not many people seem to care that `foo' isn't accepted anymore as a source code quote and just keep using it instead of `foo`.

Thanks and bye,


Simon

PS: Btw, I don't think it is strictly necessary to "fix all the standard library". Scala isn't the only language out there where the implementation doesn't follow the recommended practice to 100%. Apart from that, I would have no problem sitting down and fixing the standard library.

[martin odersky]

Let's just take a step back. So far, I hear one opinion from Simon and another opinion from everyone else.

Given that the recommendation in the Scaladoc document was made without consultation with the Scala community by I do not know who, and none of the original contributors speak up in favor here, let's bring this to a close:

First, Scaladoc needs to be fixed so that it conforms to any start of line convention.

Second, the Scaladoc recommendations should be brought in line with what everyone else is using. That style should be kept for the documentation of the standard library and compiler.

 -- Martin

[Ruediger Keller]

Currently Scaladoc does the following (just checked the code):

When removing the left gutter of a comment it first removes the leading /* and then on every line all starting whitespace, the first * and one additional whitespace is removed. This works for plain old Javadoc style comments and also for newly proposed style. It's only problematic when using the old school Javadoc style but writing the comment starting from the first line:

/** This is problematic because for Scaladoc this first
 *  line is indented with zero whitespaces and all the
 *  following lines are indented with one whitespace.
 */

turns into ==>

This is problematic because for Scaladoc this first
 line is indented with zero whitespaces and all the
 following lines are indented with one whitespace.

But this is also only really a problem when using wiki syntax on the first line that's relying on indentation. Like starting a list on the first line of the comment. Probably not an often used feature.

So does Scaladoc need fixing and if yes, what needs to be changed?

Regards,
Rüdiger


2011/5/9 martin odersky <martin....@epfl.ch>:

[Simon Ochsenreither]

Hi,

> Let's just take a step back. So far, I hear one opinion from Simon and
> another opinion from everyone else.
>
> Given that the recommendation in the Scaladoc document was made
> without consultation with the Scala community by I do not know who,
> and none of the original contributors speak up in favor here, let's
> bring this to a close:

Maybe they don't checked their emails yet. It is just 3 hours since the
discussion started.

> First, Scaladoc needs to be fixed so that it conforms to any start of
> line convention.
>
> Second, the Scaladoc recommendations should be brought in line with
> what everyone else is using. That style should be kept for the
> documentation of the standard library and compiler.

Sometimes an improvement seems to be not worth the amount of discussion
it generates. :-(

Judging from the amount of mails this has already generated in less than
3 hours, I'm in favor of this fast decision, even if it reverts the
improvements made in 2.8 instead of loosing time with endless discussions.

Thanks and bye,

Simon

[Randall R Schulz]

On Monday May 9 2011, Stuart Roebuck wrote:
> It does feel like a solution looking for a problem and causing one!
>
> The vast majority of code is of the form:
>
> /**
> * COMMENTS GO HERE
> * AND HERE
> * ETC
> */
>

> ...

Do we have to use the silly stars down the left hand side? What purpose
do they serve?

> Stuart.

Randall Schulz

[Elazar Leibovich]

You can see instantly that a long comment is a comment. Think for example for a comment which contains code samples.

 

> Stuart.


Randall Schulz

[Randall R Schulz]

How can you fail to see that even in the absence of the asterisks?

Randall Schulz

[Paul Phillips]

On 5/9/11 9:52 PM, Elazar Leibovich wrote:
> You can see instantly that a long comment is a comment. Think for
> example for a comment which contains code samples.

That argument would have held a little more water twenty years ago.
Syntax highlighting is ubiquitous: if you don't have or choose not to
use syntax highlighting, you are either hard-core old school or pretty
out of touch with the tools. We know it can compile scala programs so
it's not a vic-20 or anything. But whatever the underlying reasoning,
it's only applicable to a small minority.

[Elazar Leibovich]

Just clarifying, I generally agree with Paul's view here. I was just presenting argument I heard once in C++ lessons, featuring code with hard-to-find bugs due to multiline comments.

[Stefan Wagner]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am 10.05.2011 05:31, schrieb Randall R Schulz:

>> /**
>> * COMMENTS GO HERE
>> * AND HERE
>> * ETC
>> */
>>
>> ...
>
> Do we have to use the silly stars down the left hand side? What purpose
> do they serve?

I would prefere code-blocks of the form:

/** COMMENTS GO HERE
AND HERE
AND HERE
ETC */
def dummy (foo: Foo)

without unused stars, or better:

/** COMMENTS GO HERE
AND HERE
AND HERE
ETC */
def dummy (foo: Foo)

For html, a line.trim () should remove all leading and trailing blanks.

- --

Tschööö--->...Stefan
- ---------------------------
Don't visit my homepage at:
http://home.arcor-online.net/hirnstrom
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk3KCs0ACgkQQeATqGpDnRqt9ACeOHoRHsN1cVLvDBaQNkChSi0p
hhAAmgKkOfIiTafHFaggGeAc372ZJ3K3
=pUUl
-----END PGP SIGNATURE-----

[Simon Ochsenreither]

+1

[Philippe Lhoste]

On 11/05/2011 06:04, Stefan Wagner wrote:
> Am 10.05.2011 05:31, schrieb Randall R Schulz:
>>> /**
>>> * COMMENTS GO HERE
>>> * AND HERE
>>> * ETC
>>> */
>>

>> Do we have to use the silly stars down the left hand side? What purpose
>> do they serve?
>
> I would prefere code-blocks of the form:
>
> /** COMMENTS GO HERE
> AND HERE
> AND HERE
> ETC */
> def dummy (foo: Foo)
>
> without unused stars, or better:
>
> /** COMMENTS GO HERE
> AND HERE
> AND HERE
> ETC */
> def dummy (foo: Foo)

Yes, there are lot of tastes, like for whitespace handling for indentation, choice of
brace positions, and so on.
Everybody has a different concept of readability, and then there is tradition, JavaDoc
being firmly planted in many developer's minds, and even Qt, thus Doxygen, reused the
convention for C++ (and more) code.

So, the best is to make a flexible tool able to handle all these styles. If not by
auto-discovering, at least by some settings.

As a reminder, speaking of Doxygen, we already debated the advantages of commenting
method's parameters inline, instead of repeating parameter names in the doc, which is
prone to desynchronization (method changes, comments are forgotten):

def someMethod(
foo: Int, ///< A number
bar: String, ///< The message
zot: Boolean ///< An option
)

Here, the doc tool automatically extract information from the code, instead of having the
developer to manually repeat them (even if IDEs can help, not everybody use them).

--
Philippe Lhoste
-- (near) Paris -- France
-- http://Phi.Lho.free.fr
-- -- -- -- -- -- -- -- -- -- -- -- -- --

[Daniel Sobral]

On Wed, May 11, 2011 at 01:04, Stefan Wagner <hirn...@arcor.de> wrote:

> /** COMMENTS GO HERE
>    AND HERE
>    AND HERE
>    ETC */
> def dummy (foo: Foo)
>
> For html, a line.trim () should remove all leading and trailing blanks.

That doesn't work with wiki markup.

--
Daniel C. Sobral

I travel to the future all the time.

[Gilles Dubochet]

The Scaladoc documentation for authors has a thorough specification of how left margins are inferred by Scaladoc.

Basically, I think that Scaladoc supports all documentation styles mentioned in this thread, with the exception of the following:

/** Some comments

    multiple left whitespace and no star character */

In such a case, the wiki parser will assume that the left margin of the second line is its first character, and wiki syntax that depends on the distance to the margin (lists form example) will be incorrectly parsed.

The Scala style described in the documentation and now supported by IntelliJ was recommended because it is easier to read: the left margin on all lines (including the first) is on the same column.

However, I agree that it would be good if IntelliJ would allows selecting different styles in its options.

Cheers,

Gilles. 

[Jason Zaugg]

On Sat, May 14, 2011 at 1:28 PM, Gilles Dubochet
<gilles....@epfl.ch> wrote:
> However, I agree that it would be good if IntelliJ would allows selecting
> different styles in its options.

It does: Settings, Code Style, Spacing, Scala, Scaladoc2 Formatting.

-jason

[Josh Suereth]

I think we need an intercal-y feature where you must provide enough ascii artsy astectics in code, perhaps a self portrait, for scaladoc to generate any documentation.  

[Kevin Wright]

On 14 May 2011 15:08, Josh Suereth <joshua....@gmail.com> wrote:

I think we need an intercal-y feature where you must provide enough ascii artsy astectics in code, perhaps a self portrait, for scaladoc to generate any documentation.  

If going down that route, then at least one literary annotation from GAG should be made compulsory on each and every method name:

http://code.google.com/p/gag/

 

On May 10, 2011 1:28 AM, "Paul Phillips" <pa...@improving.org> wrote:
> On 5/9/11 9:52 PM, Elazar Leibovich wrote:
>> You can see instantly that a long comment is a comment. Think for
>> example for a comment which contains code samples.
>
> That argument would have held a little more water twenty years ago.
> Syntax highlighting is ubiquitous: if you don't have or choose not to
> use syntax highlighting, you are either hard-core old school or pretty
> out of touch with the tools. We know it can compile scala programs so
> it's not a vic-20 or anything. But whatever the underlying reasoning,
> it's only applicable to a small minority.

--
Kevin Wright

gtalk / msn : kev.lee...@gmail.com

mail: kevin....@scalatechnology.com

vibe / skype: kev.lee.wright

quora: http://www.quora.com/Kevin-Wright
twitter: @thecoda

"My point today is that, if we wish to count lines of code, we should not regard them as "lines produced" but as "lines spent": the current conventional wisdom is so foolish as to book that count on the wrong side of the ledger" ~ Dijkstra

[Piotr Kołaczkowski]

W dniu 2011-05-09 19:10, martin odersky pisze:

> Let's just take a step back. So far, I hear one opinion from Simon and
> another opinion from everyone else.

I personally like the ScalaDoc2 comment convention very much.
I've already been writing comments like that for quite long and I'm very
happy that IntelliJ now supports it.

Regards,
Piotr