Order between annotation and javadoc is significant and can lead to missing javadoc or crash

[murdos]

Overview of the issue

While doing some tests with the customs annotations from https://github.com/jhipster/jhipster-core/pull/349 from master version, I noticed several issues related to the order of javadoc and annotations:

On entity level:

Works:

@dto(mapstruct)
/** entity javadoc */
entity A {
  /** field javadoc */ name String
}

However with the following jdl, the javadoc is silently dropped:

/** entity javadoc */
@dto(mapstruct)
entity A {
  /** field javadoc */ name String
}

On field level:

Works:

/** entity javadoc */
entity A {
  @id /** field javadoc */ name String
}

Crashes:

/** entity javadoc */
entity A {
  /** field javadoc */ 
  @id name String
}

with the error:

INFO! The JDL is being parsed.
error: Error message:
    MismatchedTokenException: Expecting token of type --> NAME <-- but found --> '@' <--
    at line: 4, column: 3
SyntaxError: Error: MismatchedTokenException: Expecting token of type --> NAME <-- but found --> '@' <--
    at line: 4, column: 3
Error while parsing applications and entities from the JDL SyntaxError: Error: MismatchedTokenException: Expecting token of type --> NAME <-- but found --> '@' <--
    at line: 4, column: 3
SyntaxError: Error: MismatchedTokenException: Expecting token of type --> NAME <-- but found --> '@' <--

Motivation for or Use Case

Similarly to what’s possible in Java, it should be possible to add javadoc before annotation and the other way round. The javadoc should not be silently dropped or makes the parser crashes.

Reproduce the error

See above

Related issues

Suggest a Fix

No idea! 😁

JHipster Version(s)

6.3.0 with jhipster-core master

JHipster configuration

Entity configuration(s) entityName.json files generated in the .jhipster directory

Browsers and Operating System

• [X] Checking this box is mandatory (this is just to show you read everything)

[MathieuAA]

Outch, thanks for reporting this one. I'll see about this this week-end

[MathieuAA]

For the entity issue:

• I'm gonna implement case 2 but forbid case 1, and so make the order matter:
  • comment
  • annotation(s)
  • entity
• that's gonna be a breaking change (but I already have to release a major version, so that's almost okay)

For the field issue:

• implement the same rule
• forbid case 1

[murdos]

Thanks, case 2 is indeed more fluent. Just wondering: is there's any technical difficulty in support both cases? I saw that for fields there are already 2 different places for javadoc according to documentation:

entity A {
  name String /** My super field */
}

and

entity A {
  /** My super field */ name String
}

[MathieuAA]

Nop, not if whitespaces are involved. As they are ignored, the placement is whatever you want it to be