ScalaDoc2 Spurious Diagnostics

Hello,

I think the rationale behind this (having every line aligned with *s) is that it is then easier to distinguish/handle wiki syntax for list enumerators.

Manohar

On Tue, Feb 16, 2010 at 7:50 PM, Randall R Schulz <rschulz@sonic.net> wrote:

Hi,

I have lots of documentation comments that look like this:

/**
   Doc doc doc
   doc doc doc doc
*/

These produce the diagnostic "Comment has no start-of-line marker
('*')". This diagnostic is also produced for a comment like this:

   /** Ascertain whether this <b>Substitution</b> is <i>nilpotent</i>,
       i.e., does not change any term to which it is applied */


I also have many doc-comments-in-waiting (placeholders) that look like
this:

/** */

or this:

/***/

These produce "Comment must start with sentence".


Each of these elicits a diagnostic from the ScalaDoc processor in
2.8.0.Beta1. It would be nice if they were handled without complaint.

And please don't force me to line the left side of my (multi-line)
documentation comments with asterisks.


Randall Schulz

On Tuesday February 16 2010, Manohar Jonnalagedda wrote:
> Hello,
>
> I think the rationale behind this (having every line aligned with *s)
> is that it is then easier to distinguish/handle wiki syntax for list
> enumerators.

I don't understand. What's the issue? Why isn't JavaDoc's processing
adequate? It doesn't have these problems.

> Manohar

Randall Schulz

The idea is to allow wiki-style comments in scaladoc, to be able to parse them and display them correctly in the generated documentation. To my knowledge (and recently tested), this is not possible in Javadoc.

Consider the following :

/**
 * Comment line 1
 * Comment line 2
 * Comment line 3
 */

How do we interpret the three comment lines ? Is it part of a bullet-list, or are they to be treated as normal comments ? In such cases, it would be rather better not to have such ambiguities. The reason it was decided that each line should contain an extra asterisk, than not, is because most IDEs automatically generate this asterisk.

Cheers,
Manohar


On Tue, Feb 16, 2010 at 10:57 PM, Randall R Schulz <rschulz@sonic.net> wrote:

On Tuesday February 16 2010, Manohar Jonnalagedda wrote:
> Hello,
>
> I think the rationale behind this (having every line aligned with *s)
> is that it is then easier to distinguish/handle wiki syntax for list
> enumerators.

I don't understand. What's the issue? Why isn't JavaDoc's processing
adequate? It doesn't have these problems.


> Manohar


Randall Schulz

Is it possible to demand the leading * only when wiki-like lists are
used in that comment?
Or else default to beginning of line if the * is missing. I agree that
scaladoc needs to be more lenient here.

On Tuesday February 16 2010, Manohar Jonnalagedda wrote:
> The idea is to allow wiki-style comments in scaladoc, to be able to
> parse them and display them correctly in the generated documentation.
> To my knowledge (and recently tested), this is not possible in
> Javadoc.
>
> Consider the following :
>
> /**
> * Comment line 1
> * Comment line 2
> * Comment line 3
> */
>
> How do we interpret the three comment lines ? Is it part of a
> bullet-list, or are they to be treated as normal comments ? In such
> cases, it would be rather better not to have such ambiguities. The
> reason it was decided that each line should contain an extra
> asterisk, than not, is because most IDEs automatically generate this
> asterisk.

Well, those asterisks are very unwelcome in my code, and IDEA allows you
to opt out of having them inserted, which I do.

Can the assumption that there's always a border of asterisks be disabled
with an option?

I've always been happy to use HTML mark-up for the fairly rare situation
of using lists in my documentation comments.

> Cheers,
> Manohar

Randall Schulz

Diverge from trac wiki syntax. It's not the holy grail, is it? Why not
use dashes for bulleted lists? Asterisks are ugly in doc comments anyways:

/**
* Here comes a list:
* * Comment line 1
* * Comment line 2
* * Comment line 3
*/

versus

/**
* Here comes a list:
* - Comment line 1
* - Comment line 2
* - Comment line 3
*/

My 2 cents,
Ingo

On 2/16/10 11:35 PM, Manohar Jonnalagedda wrote:
> The idea is to allow wiki-style comments in scaladoc, to be able to
> parse them and display them correctly in the generated documentation. To
> my knowledge (and recently tested), this is not possible in Javadoc.
>
> Consider the following :
>
> /**
> * Comment line 1
> * Comment line 2
> * Comment line 3
> */
>
> How do we interpret the three comment lines ? Is it part of a
> bullet-list, or are they to be treated as normal comments ? In such
> cases, it would be rather better not to have such ambiguities. The
> reason it was decided that each line should contain an extra asterisk,
> than not, is because most IDEs automatically generate this asterisk.
>
> Cheers,
> Manohar
>
>
> On Tue, Feb 16, 2010 at 10:57 PM, Randall R Schulz > wrote:
>
> On Tuesday February 16 2010, Manohar Jonnalagedda wrote:
> > Hello,
> >
> > I think the rationale behind this (having every line aligned with *s)
> > is that it is then easier to distinguish/handle wiki syntax for list
> > enumerators.
>
> I don't understand. What's the issue? Why isn't JavaDoc's processing
> adequate? It doesn't have these problems.
>
>
> > Manohar
>
>
> Randall Schulz
>
>

Hello all,

after dicussions with Gilles and Pedro Furlanetto on the subject, it has been decided that the best idea will be to :

- remove the annoying constraint that each comment line should start with an asterisk
- solve the enumeration problem by implementing Ingo's suggestion of using dashes ('-')

Hope this will be satisfactory for most people.

Best,
Manohar

On Wed, Feb 17, 2010 at 7:55 AM, Ingo Maier <ingo.maier@epfl.ch> wrote:

Diverge from trac wiki syntax. It's not the holy grail, is it? Why not use dashes for bulleted lists? Asterisks are ugly in doc comments anyways:

/**
 * Here comes a list:
 * * Comment line 1
 * * Comment line 2
 * * Comment line 3
 */

versus

/**
 * Here comes a list:
 * - Comment line 1
 * - Comment line 2
 * - Comment line 3
 */

My 2 cents,
Ingo

On 2/16/10 11:35 PM, Manohar Jonnalagedda wrote:

The idea is to allow wiki-style comments in scaladoc, to be able to
parse them and display them correctly in the generated documentation. To
my knowledge (and recently tested), this is not possible in Javadoc.

Consider the following :

/**
 * Comment line 1
 * Comment line 2
 * Comment line 3
 */

How do we interpret the three comment lines ? Is it part of a
bullet-list, or are they to be treated as normal comments ? In such
cases, it would be rather better not to have such ambiguities. The
reason it was decided that each line should contain an extra asterisk,
than not, is because most IDEs automatically generate this asterisk.

Cheers,
Manohar


On Tue, Feb 16, 2010 at 10:57 PM, Randall R Schulz <rschulz@sonic.net
<mailto:rschulz@sonic.net>> wrote:

   On Tuesday February 16 2010, Manohar Jonnalagedda wrote:
    > Hello,
    >
    > I think the rationale behind this (having every line aligned with *s)
    > is that it is then easier to distinguish/handle wiki syntax for list
    > enumerators.

   I don't understand. What's the issue? Why isn't JavaDoc's processing
   adequate? It doesn't have these problems.


    > Manohar


   Randall Schulz

On Tuesday February 23 2010, Manohar Jonnalagedda wrote:
> Hello all,
>
> after dicussions with Gilles and Pedro Furlanetto on the subject, it
> has been decided that the best idea will be to :
>
> - remove the annoying constraint that each comment line should start
> with an asterisk
> - solve the enumeration problem by implementing Ingo's suggestion of
> using dashes ('-')
>
> Hope this will be satisfactory for most people.

I'm fine with it.

> Best,
> Manohar

Randall Schulz