This page is no longer maintained — Please continue to the home page at www.scala-lang.org

scaladoc 2 convention on indenting scaladoc comments

14 replies
stuartroebuck
Joined: 2010-03-17,
User offline. Last seen 44 weeks 3 days ago.
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.
odersky
Joined: 2008-07-29,
User offline. Last seen 45 weeks 6 days ago.
Re: scaladoc 2 convention on indenting scaladoc comments
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


On Mon, May 9, 2011 at 3:52 PM, Stuart Roebuck <stuart [dot] roebuck [at] gmail [dot] com> wrote:
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
Prof., EPFL and CEO, Scala Solutions
PSED, 1015 Lausanne, Switzerland


Rüdiger Keller
Joined: 2010-01-24,
User offline. Last seen 42 years 45 weeks ago.
Re: scaladoc 2 convention on indenting scaladoc comments

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

alois.cochard
Joined: 2010-03-19,
User offline. Last seen 34 weeks 3 hours ago.
Re: scaladoc 2 convention on indenting scaladoc comments
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 ?
Johannes Rudolph 2
Joined: 2010-02-12,
User offline. Last seen 42 years 45 weeks ago.
Re: scaladoc 2 convention on indenting scaladoc comments

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.

On Mon, May 9, 2011 at 4:29 PM, Rüdiger Keller
wrote:
> 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 :
>> 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.
>>
>

rytz
Joined: 2008-07-01,
User offline. Last seen 45 weeks 5 days ago.
Re: scaladoc 2 convention on indenting scaladoc comments
I was also very surprised to see that today.Until seeing this message I thought it was a bug in IntelliJ.

On Mon, May 9, 2011 at 15:52, Stuart Roebuck <stuart [dot] roebuck [at] gmail [dot] com> wrote:
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.

ichoran
Joined: 2009-08-14,
User offline. Last seen 2 years 3 weeks ago.
Re: scaladoc 2 convention on indenting scaladoc comments
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

On Mon, May 9, 2011 at 10:36 AM, Johannes Rudolph <johannes [dot] rudolph [at] googlemail [dot] com> wrote:
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.

On Mon, May 9, 2011 at 4:29 PM, Rüdiger Keller
<ruediger [dot] keller [at] googlemail [dot] com> wrote:
> 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 [dot] roebuck [at] gmail [dot] com>:
>> 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.
>>
>



--
Johannes

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

odersky
Joined: 2008-07-29,
User offline. Last seen 45 weeks 6 days ago.
Re: scaladoc 2 convention on indenting scaladoc comments


On Mon, May 9, 2011 at 5:01 PM, Rex Kerr <ichoran [at] gmail [dot] 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
Joined: 2010-01-24,
User offline. Last seen 42 years 45 weeks ago.
Re: scaladoc 2 convention on indenting scaladoc comments

2011/5/9 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 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

Johannes Rudolph 2
Joined: 2010-02-12,
User offline. Last seen 42 years 45 weeks ago.
Re: scaladoc 2 convention on indenting scaladoc comments

On Mon, May 9, 2011 at 5:16 PM, Rüdiger Keller
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.

Rüdiger Keller
Joined: 2010-01-24,
User offline. Last seen 42 years 45 weeks ago.
Re: scaladoc 2 convention on indenting scaladoc comments

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 :
> On Mon, May 9, 2011 at 5:16 PM, Rüdiger Keller
> 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

-tag it uses only one blank so that the inner
> code is aligned.
>
>
> -----------------------------------------------
> Johannes Rudolph
> http://virtual-void.net
>
Jason Zaugg
Joined: 2009-05-18,
User offline. Last seen 38 weeks 5 days ago.
Re: scaladoc 2 convention on indenting scaladoc comments

On Mon, May 9, 2011 at 5:31 PM, Johannes Rudolph
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

Chris Twiner
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: scaladoc 2 convention on indenting scaladoc comments

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" <ruediger [dot] keller [at] googlemail [dot] 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 [dot] rudolph [at] googlemail [dot] com>:

> On Mon, May 9, 2011 at 5:16 PM, Rüdiger Keller
> <ruediger [dot] keller [at] googlemail [dot] com> wrote:
>> I don'...

dubochet
Joined: 2008-06-30,
User offline. Last seen 1 year 36 weeks ago.
Re: scaladoc 2 convention on indenting scaladoc comments
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
Joined: 2009-05-18,
User offline. Last seen 38 weeks 5 days ago.
Re: scaladoc 2 convention on indenting scaladoc comments

On Sat, May 14, 2011 at 1:28 PM, Gilles Dubochet
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

Copyright © 2012 École Polytechnique Fédérale de Lausanne (EPFL), Lausanne, Switzerland