doc: adding Javadoc tags to CtImport

[rishivijayv]

#3923

This adds Javadoc tags (@param and @return) to the methods of the CtImport interface. Using the check-javadoc-regressions.py now does not show any Javadoc errors in the CtImport.java file.

Before the change

$ chore/run-with-spoon-javadoc-classpath.sh chore/CheckJavadoc.java
SLF4J(W): No SLF4J providers were found.
SLF4J(W): Defaulting to no-operation (NOP) logger implementation
SLF4J(W): See https://www.slf4j.org/codes.html#noProviders for further details.
SLF4J(W): Class path contains SLF4J bindings targeting slf4j-api versions 1.7.x or earlier.
SLF4J(W): Ignoring binding found at [jar:file:/Users/rishivijayvargiya/.m2/repository/org/slf4j/slf4j-nop/1.7.36/slf4j-nop-1.7.36.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J(W): See https://www.slf4j.org/codes.html#ignoredBindings for an explanation.
[ERROR] src/main/java/spoon/reflect/declaration/CtImport.java:40:15: Missing @return tag in getImportKind()
[ERROR] src/main/java/spoon/reflect/declaration/CtImport.java:46:14: Missing @return tag in getReference()
[ERROR] src/main/java/spoon/reflect/declaration/CtImport.java:53:25: Missing @param 'reference' tag in setReference(CtReference)
[ERROR] src/main/java/spoon/reflect/declaration/CtImport.java:53:25: Missing @param '<T>' tag in setReference(CtReference)
[ERROR] src/main/java/spoon/reflect/declaration/CtImport.java:53:25: Missing @return tag in setReference(CtReference)
[ERROR] src/main/java/spoon/reflect/declaration/CtImport.java:58:7: Missing @param 'visitor' tag in accept(CtImportVisitor)

After the change

$ chore/run-with-spoon-javadoc-classpath.sh chore/CheckJavadoc.java
SLF4J(W): No SLF4J providers were found.
SLF4J(W): Defaulting to no-operation (NOP) logger implementation
SLF4J(W): See https://www.slf4j.org/codes.html#noProviders for further details.
SLF4J(W): Class path contains SLF4J bindings targeting slf4j-api versions 1.7.x or earlier.
SLF4J(W): Ignoring binding found at [jar:file:/Users/rishivijayvargiya/.m2/repository/org/slf4j/slf4j-nop/1.7.36/slf4j-nop-1.7.36.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J(W): See https://www.slf4j.org/codes.html#ignoredBindings for an explanation.

[rishivijayv]

Per https://stackoverflow.com/a/25957713, it seems that only having tags without a main description section is also acceptable. So adopting that approach here as I think that avoids some repetition.

[I-Al-Istannen]

The "modern" way is using the inline returns tag: {@return the kind of import...}. This will automatically create a doc comment body in the expected format for you. See https://docs.oracle.com/en/java/javase/22/docs/specs/javadoc/doc-comment-spec.html#return :)

[rishivijayv]

Ahh should have scrolled a little further down the very link that I posted here haha 😅 This is pretty nifty, thanks! Adjusted now!