From d06df38c5e48ae8c957c4b71844cb850dea3a6cb Mon Sep 17 00:00:00 2001 From: "Paolo G. Giarrusso" Date: Wed, 25 May 2016 17:41:21 +0200 Subject: [PATCH 1/2] Fix errors with Javadoc 8 `sbt dotty-interfaces/publishLocal` fails for me, fix enough errors to make it work. --- .../main/java/dotty/tools/dotc/interfaces/CompilerCallback.java | 2 +- .../main/java/dotty/tools/dotc/interfaces/SimpleReporter.java | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/interfaces/src/main/java/dotty/tools/dotc/interfaces/CompilerCallback.java b/interfaces/src/main/java/dotty/tools/dotc/interfaces/CompilerCallback.java index 17d2f6bbdf43..25696f74041b 100644 --- a/interfaces/src/main/java/dotty/tools/dotc/interfaces/CompilerCallback.java +++ b/interfaces/src/main/java/dotty/tools/dotc/interfaces/CompilerCallback.java @@ -5,7 +5,7 @@ * You should implement this interface if you want to react to one or more of * these events. * - * @see the method `process` of `dotty.tools.dotc.Driver` for more information. + * See the method `process` of `dotty.tools.dotc.Driver` for more information. */ public interface CompilerCallback { /** Called when a class has been generated. diff --git a/interfaces/src/main/java/dotty/tools/dotc/interfaces/SimpleReporter.java b/interfaces/src/main/java/dotty/tools/dotc/interfaces/SimpleReporter.java index e52537096bd9..872448583e5b 100644 --- a/interfaces/src/main/java/dotty/tools/dotc/interfaces/SimpleReporter.java +++ b/interfaces/src/main/java/dotty/tools/dotc/interfaces/SimpleReporter.java @@ -5,7 +5,7 @@ * You should implement this interface if you want to handle the diagnostics * returned by the compiler yourself. * - * @see the method `process` of `dotty.tools.dotc.Driver` for more information. + * See the method `process` of `dotty.tools.dotc.Driver` for more information. */ public interface SimpleReporter { /** Report a diagnostic. */ From 0577280bd19eafee12c590ba280916b5b9b307ad Mon Sep 17 00:00:00 2001 From: "Paolo G. Giarrusso" Date: Wed, 25 May 2016 18:03:44 +0200 Subject: [PATCH 2/2] Fix remaining Javadoc warnings As a reference for how to fix warnings appropriately, I used http://www.oracle.com/technetwork/articles/java/index-137868.html However, I did not refrain from moving the entire JavaDoc of a method into `@return` rather than repeating it, even though the guide (at a quick skimming) seems to suggest otherwise. --- .../tools/dotc/interfaces/AbstractFile.java | 6 +++--- .../tools/dotc/interfaces/Diagnostic.java | 6 +++--- .../tools/dotc/interfaces/ReporterResult.java | 8 +++---- .../tools/dotc/interfaces/SimpleReporter.java | 4 +++- .../tools/dotc/interfaces/SourceFile.java | 2 +- .../tools/dotc/interfaces/SourcePosition.java | 21 ++++++++++--------- 6 files changed, 25 insertions(+), 22 deletions(-) diff --git a/interfaces/src/main/java/dotty/tools/dotc/interfaces/AbstractFile.java b/interfaces/src/main/java/dotty/tools/dotc/interfaces/AbstractFile.java index a1b9cc5c7beb..286e7b2cf51d 100644 --- a/interfaces/src/main/java/dotty/tools/dotc/interfaces/AbstractFile.java +++ b/interfaces/src/main/java/dotty/tools/dotc/interfaces/AbstractFile.java @@ -11,13 +11,13 @@ * manipulate objects of this type. */ public interface AbstractFile { - /** The name of this file, note that two files may have the same name. */ + /** @return The name of this file, note that two files may have the same name. */ String name(); - /** The path of this file, this might be a virtual path of an unspecified format. */ + /** @return The path of this file, this might be a virtual path of an unspecified format. */ String path(); - /** If this is a real file on disk, a `java.io.File` that corresponds to this file. + /** @return If this is a real file on disk, a `java.io.File` that corresponds to this file. * Otherwise, an empty `Optional`. */ Optional jfile(); diff --git a/interfaces/src/main/java/dotty/tools/dotc/interfaces/Diagnostic.java b/interfaces/src/main/java/dotty/tools/dotc/interfaces/Diagnostic.java index 436f9f8ea823..c46360afaa3d 100644 --- a/interfaces/src/main/java/dotty/tools/dotc/interfaces/Diagnostic.java +++ b/interfaces/src/main/java/dotty/tools/dotc/interfaces/Diagnostic.java @@ -14,13 +14,13 @@ public interface Diagnostic { public static final int WARNING = 1; public static final int INFO = 0; - /** The message to report */ + /** @return The message to report */ String message(); - /** Level of the diagnostic, can be either ERROR, WARNING or INFO */ + /** @return Level of the diagnostic, can be either ERROR, WARNING or INFO */ int level(); - /** The position in a source file of the code that caused this diagnostic + /** @return The position in a source file of the code that caused this diagnostic * to be emitted. */ Optional position(); } diff --git a/interfaces/src/main/java/dotty/tools/dotc/interfaces/ReporterResult.java b/interfaces/src/main/java/dotty/tools/dotc/interfaces/ReporterResult.java index 63c5104dff9f..f75519db2d2e 100644 --- a/interfaces/src/main/java/dotty/tools/dotc/interfaces/ReporterResult.java +++ b/interfaces/src/main/java/dotty/tools/dotc/interfaces/ReporterResult.java @@ -6,13 +6,13 @@ * manipulate objects of this type. */ public interface ReporterResult { - /** Have we emitted any error ? */ + /** @return Have we emitted any error? */ boolean hasErrors(); - /** Number of errors that have been emitted */ + /** @return Number of errors that have been emitted */ int errorCount(); - /** Have we emitted any warning ? */ + /** @return Have we emitted any warning ? */ boolean hasWarnings(); - /** Number of warnings that have been emitted */ + /** @return Number of warnings that have been emitted */ int warningCount(); } diff --git a/interfaces/src/main/java/dotty/tools/dotc/interfaces/SimpleReporter.java b/interfaces/src/main/java/dotty/tools/dotc/interfaces/SimpleReporter.java index 872448583e5b..f4c80c0cf996 100644 --- a/interfaces/src/main/java/dotty/tools/dotc/interfaces/SimpleReporter.java +++ b/interfaces/src/main/java/dotty/tools/dotc/interfaces/SimpleReporter.java @@ -8,6 +8,8 @@ * See the method `process` of `dotty.tools.dotc.Driver` for more information. */ public interface SimpleReporter { - /** Report a diagnostic. */ + /** Report a diagnostic. + * @param diag the diagnostic message to report + */ void report(Diagnostic diag); } diff --git a/interfaces/src/main/java/dotty/tools/dotc/interfaces/SourceFile.java b/interfaces/src/main/java/dotty/tools/dotc/interfaces/SourceFile.java index 5611d388587d..0e16d3ea4ba9 100644 --- a/interfaces/src/main/java/dotty/tools/dotc/interfaces/SourceFile.java +++ b/interfaces/src/main/java/dotty/tools/dotc/interfaces/SourceFile.java @@ -8,6 +8,6 @@ * manipulate objects of this type. */ public interface SourceFile extends AbstractFile { - /** The content of this file as seen by the compiler. */ + /** @return The content of this file as seen by the compiler. */ char[] content(); } diff --git a/interfaces/src/main/java/dotty/tools/dotc/interfaces/SourcePosition.java b/interfaces/src/main/java/dotty/tools/dotc/interfaces/SourcePosition.java index c9b42d4ad213..d8afbf5f607a 100644 --- a/interfaces/src/main/java/dotty/tools/dotc/interfaces/SourcePosition.java +++ b/interfaces/src/main/java/dotty/tools/dotc/interfaces/SourcePosition.java @@ -12,33 +12,34 @@ * manipulate objects of this type. */ public interface SourcePosition { - /** Content of the line which contains the point */ + /** @return Content of the line which contains the point */ String lineContent(); - /** Offset to the point */ + /** @return Offset to the point */ int point(); - /** Line number of the point, starting at 0 */ + /** @return Line number of the point, starting at 0 */ int line(); - /** Column number of the point, starting at 0 */ + /** @return Column number of the point, starting at 0 */ int column(); - /** Offset to the range start */ + /** @return Offset to the range start */ int start(); - /** Line number of the range start, starting at 0 */ + /** @return Line number of the range start, starting at 0 */ int startLine(); - /** Column number of the range start, starting at 0 */ + /** @return Column number of the range start, starting at 0 */ int startColumn(); - /** Offset to the range end */ + /** @return Offset to the range end */ int end(); - /** Line number of the range end, starting at 0 */ + /** @return Line number of the range end, starting at 0 */ int endLine(); - /** Column number of the range end, starting at 0 */ + /** @return Column number of the range end, starting at 0 */ int endColumn(); /** The source file corresponding to this position. * The values returned by `point()`, `start()` and `end()` * are indices in the array returned by `source().content()`. + * @return source file for this position */ SourceFile source(); }