From 0577280bd19eafee12c590ba280916b5b9b307ad Mon Sep 17 00:00:00 2001
From: "Paolo G. Giarrusso"
Date: Wed, 25 May 2016 18:03:44 +0200
Subject: 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.
---
.../dotty/tools/dotc/interfaces/AbstractFile.java | 6 +++---
.../dotty/tools/dotc/interfaces/Diagnostic.java | 6 +++---
.../dotty/tools/dotc/interfaces/ReporterResult.java | 8 ++++----
.../dotty/tools/dotc/interfaces/SimpleReporter.java | 4 +++-
.../dotty/tools/dotc/interfaces/SourceFile.java | 2 +-
.../dotty/tools/dotc/interfaces/SourcePosition.java | 21 +++++++++++----------
6 files changed, 25 insertions(+), 22 deletions(-)
(limited to 'interfaces')
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 a1b9cc5c7..286e7b2cf 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 @@ import java.util.Optional;
* 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 436f9f8ea..c46360afa 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 63c5104df..f75519db2 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 @@ package dotty.tools.dotc.interfaces;
* 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 872448583..f4c80c0cf 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 @@ package dotty.tools.dotc.interfaces;
* 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 5611d3885..0e16d3ea4 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 @@ import java.io.File;
* 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 c9b42d4ad..d8afbf5f6 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 @@ package dotty.tools.dotc.interfaces;
* 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();
}
--
cgit v1.2.3