Improve javadoc.

4 files changed, 78 insertions, 13 deletions

diff --git a/src/main/java/org/anarres/cpp/LexerSource.java b/src/main/java/org/anarres/cpp/LexerSource.java
index 82d76b6..931f4a7 100644
--- a/src/main/java/org/anarres/cpp/LexerSource.java
+++ b/src/main/java/org/anarres/cpp/LexerSource.java
@@ -68,11 +68,25 @@ public class LexerSource extends Source {
         this.reader.init(pp, this);
     }
 
+    /**
+     * Returns the line number of the last read character in this source.
+     *
+     * Lines are numbered from 1.
+     *
+     * @return the line number of the last read character in this source.
+     */
     @Override
     public int getLine() {
         return line;
     }
 
+    /**
+     * Returns the column number of the last read character in this source.
+     *
+     * Columns are numbered from 0.
+     *
+     * @return the column number of the last read character in this source.
+     */
     @Override
     public int getColumn() {
         return column;
@@ -513,8 +527,7 @@ public class LexerSource extends Source {
                 flags |= NumericValue.F_DOUBLE;
                 text.append((char) d);
                 d = read();
-            }
-            else if (Character.isUnicodeIdentifierPart(d)) {
+            } else if (Character.isUnicodeIdentifierPart(d)) {
                 String reason = "Invalid suffix \"" + (char) d + "\" on numeric constant";
                 // We've encountered something initially identified as a number.
                 // Read in the rest of this token as an identifer but return it as an invalid.
@@ -628,9 +641,9 @@ public class LexerSource extends Source {
 
     /**
      * Section 6.4.4.1 of C99
-     * 
+     *
      * (Not pasted here, but says that the initial negation is a separate token.)
-     * 
+     *
      * Section 6.4.4.2 of C99
      *
      * A floating constant has a significand part that may be followed
diff --git a/src/main/java/org/anarres/cpp/Preprocessor.java b/src/main/java/org/anarres/cpp/Preprocessor.java
index 27f609f..a790813 100644
--- a/src/main/java/org/anarres/cpp/Preprocessor.java
+++ b/src/main/java/org/anarres/cpp/Preprocessor.java
@@ -351,6 +351,8 @@ public class Preprocessor implements Closeable {
      *
      * The given {@link Macro} object encapsulates both the name
      * and the expansion.
+     *
+     * @throws LexerException if the definition fails or is otherwise illegal.
      */
     public void addMacro(@Nonnull Macro m) throws LexerException {
         // System.out.println("Macro " + m);
@@ -366,6 +368,8 @@ public class Preprocessor implements Closeable {
      *
      * The String value is lexed into a token stream, which is
      * used as the macro expansion.
+     *
+     * @throws LexerException if the definition fails or is otherwise illegal.
      */
     public void addMacro(@Nonnull String name, @Nonnull String value)
             throws LexerException {
@@ -389,6 +393,8 @@ public class Preprocessor implements Closeable {
      *
      * This is a convnience method, and is equivalent to
      * <code>addMacro(name, "1")</code>.
+     *
+     * @throws LexerException if the definition fails or is otherwise illegal.
      */
     public void addMacro(@Nonnull String name)
             throws LexerException {
@@ -453,6 +459,8 @@ public class Preprocessor implements Closeable {
     /**
      * Returns the Map of Macros parsed during the run of this
      * Preprocessor.
+     *
+     * @return The {@link Map} of macros currently defined.
      */
     @Nonnull
     public Map<String, Macro> getMacros() {
@@ -464,9 +472,11 @@ public class Preprocessor implements Closeable {
      *
      * While you can modify the returned object, unexpected things
      * might happen if you do.
+     *
+     * @return the Macro object, or null if not found.
      */
     @CheckForNull
-    public Macro getMacro(String name) {
+    public Macro getMacro(@Nonnull String name) {
         return macros.get(name);
     }
 
@@ -510,6 +520,8 @@ public class Preprocessor implements Closeable {
      * @see Source
      * @see #push_source(Source,boolean)
      * @see #pop_source()
+     *
+     * @return the top Source on the input stack.
      */
     // @CheckForNull
     protected Source getSource() {
@@ -519,6 +531,8 @@ public class Preprocessor implements Closeable {
     /**
      * Pushes a Source onto the input stack.
      *
+     * @param source the new Source to push onto the top of the input stack.
+     * @param autopop if true, the Source is automatically removed from the input stack at EOF.
      * @see #getSource()
      * @see #pop_source()
      */
@@ -538,6 +552,9 @@ public class Preprocessor implements Closeable {
      *
      * @see #getSource()
      * @see #push_source(Source,boolean)
+     *
+     * @param linemarker TODO: currently ignored, might be a bug?
+     * @throws IOException if an I/O error occurs.
      */
     @CheckForNull
     protected Token pop_source(boolean linemarker)
@@ -1114,10 +1131,13 @@ public class Preprocessor implements Closeable {
      *
      * User code may override this method to implement a virtual
      * file system.
+     *
+     * @param file The VirtualFile to attempt to include.
+     * @return true if the file was successfully included, false otherwise.
+     * @throws IOException if an I/O error occurs.
      */
     protected boolean include(@Nonnull VirtualFile file)
-            throws IOException,
-            LexerException {
+            throws IOException {
         // System.out.println("Try to include " + ((File)file).getAbsolutePath());
         if (!file.isFile())
             return false;
@@ -1129,11 +1149,15 @@ public class Preprocessor implements Closeable {
     }
 
     /**
-     * Includes a file from an include path, by name.
+     * Attempts to include a file from an include path, by name.
+     *
+     * @param path The list of virtual directories to search for the given name.
+     * @param name The name of the file to attempt to include.
+     * @return true if the file was successfully included, false otherwise.
+     * @throws IOException if an I/O error occurs.
      */
     protected boolean include(@Nonnull Iterable<String> path, @Nonnull String name)
-            throws IOException,
-            LexerException {
+            throws IOException {
         for (String dir : path) {
             VirtualFile file = getFileSystem().getFile(dir, name);
             if (include(file))
@@ -1144,6 +1168,9 @@ public class Preprocessor implements Closeable {
 
     /**
      * Handles an include directive.
+     *
+     * @throws IOException if an I/O error occurs.
+     * @throws LexerException if the include fails, and the error handler is fatal.
      */
     private void include(
             @CheckForNull String parent, int line,
@@ -2093,6 +2120,8 @@ public class Preprocessor implements Closeable {
      * Returns the next preprocessor token.
      *
      * @see Token
+     * @return The next fully preprocessed token.
+     * @throws IOException if an I/O error occurs.
      * @throws LexerException if a preprocessing error occurs.
      * @throws InternalException if an unexpected error condition arises.
      */
diff --git a/src/main/java/org/anarres/cpp/SourceIterator.java b/src/main/java/org/anarres/cpp/SourceIterator.java
index 82e36d9..240b3b3 100644
--- a/src/main/java/org/anarres/cpp/SourceIterator.java
+++ b/src/main/java/org/anarres/cpp/SourceIterator.java
@@ -79,7 +79,7 @@ public class SourceIterator implements Iterator<Token> {
     /**
      * Not supported.
      *
-     * @throws UnsupportedOperationException.
+     * @throws UnsupportedOperationException unconditionally.
      */
     public void remove() {
         throw new UnsupportedOperationException();
diff --git a/src/main/java/org/anarres/cpp/Token.java b/src/main/java/org/anarres/cpp/Token.java
index 3e6eb3e..b80c1ae 100644
--- a/src/main/java/org/anarres/cpp/Token.java
+++ b/src/main/java/org/anarres/cpp/Token.java
@@ -16,6 +16,9 @@
  */
 package org.anarres.cpp;
 
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
+
 /**
  * A Preprocessor token.
  *
@@ -57,6 +60,9 @@ public final class Token {
 
     /**
      * Returns the semantic type of this token.
+     *
+     * @return the semantic type of this token.
+     * @see #getTokenName(int)
      */
     public int getType() {
         return type;
@@ -70,8 +76,12 @@ public final class Token {
     /**
      * Returns the line at which this token started.
      *
-     * Lines are numbered from zero.
+     * Lines are numbered from 1.
+     *
+     * @return the line at which this token started.
+     * @see LexerSource#getLine()
      */
+    // Not @Nonnegative - might not have been assigned?
     public int getLine() {
         return line;
     }
@@ -79,8 +89,12 @@ public final class Token {
     /**
      * Returns the column at which this token started.
      *
-     * Columns are numbered from zero.
+     * Columns are numbered from 0.
+     *
+     * @return the column at which this token started.
+     * @see LexerSource#getColumn()
      */
+    // Not @Nonnegative - might not have been assigned?
     public int getColumn() {
         return column;
     }
@@ -90,8 +104,10 @@ public final class Token {
      *
      * This is distinct from the semantic value of the token.
      *
+     * @return the original or generated text of this token.
      * @see #getValue()
      */
+    // Not @Nonnull - might not have been assigned?
     public String getText() {
         return text;
     }
@@ -103,8 +119,10 @@ public final class Token {
      * For integers, this is an Integer object.
      * For other token types, as appropriate.
      *
+     * @return the semantic value of this token, or null.
      * @see #getText()
      */
+    @CheckForNull
     public Object getValue() {
         return value;
     }
@@ -138,7 +156,12 @@ public final class Token {
      * Returns the descriptive name of the given token type.
      *
      * This is mostly used for stringification and debugging.
+     *
+     * @param type The type constant from this class to name.
+     * @return the descriptive name of the given token type.
+     * @see Token#getType()
      */
+    @Nonnull
     public static String getTokenName(int type) {
         return TokenType.getTokenName(type);
     }