javadoc comments in the Java binding

19 files changed, 187 insertions, 13 deletions

diff --git a/src/runtime/java/Makefile b/src/runtime/java/Makefile
index ebad974e8..5b622f3ea 100644
--- a/src/runtime/java/Makefile
+++ b/src/runtime/java/Makefile
@@ -22,6 +22,9 @@ jpgf.jar: $(patsubst %.java, %.class, $(JAVA_SOURCES))
 install: libjpgf.la jpgf.jar
 	libtool --mode=install install -s libjpgf.la $(INSTALL_PATH)
 
+doc:
+	javadoc org.grammaticalframework.pgf org.grammaticalframework.sg -d java-api
+
 clean:
 	rm -f *.lo
 	rm -f *.la
diff --git a/src/runtime/java/org/grammaticalframework/pgf/Bracket.java b/src/runtime/java/org/grammaticalframework/pgf/Bracket.java
index faf427a05..40fb744ea 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/Bracket.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/Bracket.java
@@ -1,10 +1,24 @@
 package org.grammaticalframework.pgf;
 
+/** A bracket represents a syntactic constituent in the parse tree
+ * of a sentence. */
 public class Bracket {
+	/** The category of this bracket */
 	public final String cat;
+	
+	/** The abstract function name for the bracket */
 	public final String fun;
+	
+	/** Every constituent has an unique id. If the constituent is
+	 * discontinuous then it will be represented with several brackets
+	 * where they all will have the same id */
 	public final int fid;
+
 	public final int lindex;
+	
+	/** The children of the bracket. Every element is either a string
+	 * if this is a leaf in the parse tree, or a {@link Bracket} object.
+	 */
 	public final Object[] children;
 
 	public Bracket(String cat, String fun, int fid, int lindex, Object[] children) {
diff --git a/src/runtime/java/org/grammaticalframework/pgf/Concr.java b/src/runtime/java/org/grammaticalframework/pgf/Concr.java
index b25a83a52..891257b5a 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/Concr.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/Concr.java
@@ -3,14 +3,34 @@ package org.grammaticalframework.pgf;
 import java.io.*;
 import java.util.*;
 
+/** The class for concrete syntaxes.*/
 public class Concr {
 
 	public native String getName();
 
+	/** Parses a string with a given start category.
+	 * @param startCat the start category.
+	 * @param s the input string
+	 * @return an iterable over all abstract expressions for the input
+	 * string. The expressions are enumerated in decreasing probability order.
+	 */
 	public Iterable<ExprProb> parse(String startCat, String s) throws ParseError {
 		return new Parser(this, startCat, s, -1, null);
 	}
 
+	/** Parses a string with a given start category and specific
+	 * setup of some other parameters.
+	 * @param startCat the start category.
+	 * @param s the input string
+	 * @param heuristics this is a number from 0.0 to 1.0. Zero means
+	 * slower parsing but with accurate order of the expressions. 
+	 * One means fast but potentially inaccurate ordering of the expressions.
+	 * @param callbacks a map which assigns a callback to each literal category
+	 * in the grammar. The callbacks can be used to add custom parsing
+	 * rules for certain categories.
+	 * @return an iterable over all abstract expressions for the input
+	 * string. The expressions are enumerated in decreasing probability order.
+	 */
 	public Iterable<ExprProb> parseWithHeuristics(String startCat, String s, double heuristics, Map<String,LiteralCallback> callbacks) throws ParseError {
 		return new Parser(this, startCat, s, heuristics, callbacks);
 	}
@@ -19,24 +39,60 @@ public class Concr {
 		return new Completer(this, startCat, s, prefix);
 	}
 
+	/** Computes the linearization of the abstract expression. */
 	public native String linearize(Expr expr);
 
+	/** Linearizes the expression as an inflection table.
+	 * @return a map from the name of the inflection form to its value.
+	 */
 	public native Map<String, String> tabularLinearize(Expr expr);
 
+	/** Computes the bracketed string for the linearization of the expression.
+	 * @return an array of objects where each element is either a string
+	 * or a {@link Bracket} object.
+	 */
 	public native Object[] bracketedLinearize(Expr expr);
 
+	/** Takes a word form or a multilingual expression and
+	 * returns a list of its possible analyses according to the lexicon
+	 * in the grammar. This method is doing just lexical lookup 
+	 * without parsing.
+	 * 
+	 * @param sentence the word form or the multilingual expression.
+	 */
 	public native List<MorphoAnalysis> lookupMorpho(String sentence);
 
+	/** Returns an iterable enumerating all words in the lexicon
+	 * starting with a given prefix.
+	 * @param prefix the prefix of the word.
+	 */
 	public Iterable<FullFormEntry> lookupWordPrefix(String prefix) {
 		return new Lexicon(this, prefix);
 	}
 
-	public native boolean hasLinearization(String id);
-
+	/** returns true if a given function has linearization in this
+	 * concrete syntax.
+	 * @param fun the name of the function
+	 */
+	public native boolean hasLinearization(String fun);
+
+	/** If the concrete syntaxes in the grammar are stored in external
+	 * files then this method can be used to load the current syntax
+	 * in memory.
+	 * @param path the path to the concrete syntax file.
+	 */
 	public native void load(String path) throws FileNotFoundException;
 
+	/** If the concrete syntaxes in the grammar are stored in external
+	 * files then this method can be used to load the current syntax
+	 * in memory.
+	 * @param stream the stream from which to load the file.
+	 */
 	public native void load(InputStream stream);
 
+	/** When the syntax is no longer needed then this method can be
+	 * used to unload it.
+	 */
 	public native void unload();
 
 	//////////////////////////////////////////////////////////////////
diff --git a/src/runtime/java/org/grammaticalframework/pgf/Expr.java b/src/runtime/java/org/grammaticalframework/pgf/Expr.java
index f3ed47871..c8e6af224 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/Expr.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/Expr.java
@@ -6,6 +6,8 @@ import java.io.ObjectOutputStream;
 import java.io.Serializable;
 import java.util.Arrays;
 
+/** This class is a representation of an abstract syntax tree.
+ */
 public class Expr implements Serializable {
 		private static final long serialVersionUID = 1148602474802492674L;
 	
@@ -19,24 +21,34 @@ public class Expr implements Serializable {
 			this.ref    = ref;
 		}
 
+		/** Constructs an expression which represents a string literal */
 		public Expr(String s) {
 			this.pool   = new Pool();
 			this.master = null;
 			this.ref    = initStringLit(s, pool.ref);  
 		}
 
+		/** Constructs an expression which is a function application
+		 * @param fun The name of the top-level function.
+		 * @param args the arguments for the function.
+		 */
 		public Expr(String fun, Expr... args) {
 			this.pool   = new Pool();
 			this.master = Arrays.copyOf(args, args.length);
 			this.ref    = initApp(fun, args, pool.ref);
 		}
 
+		/** Returns the expression as a string in the GF syntax */
 		public String toString() {
 			return showExpr(ref);
 		}
 
+		/** Reads a string in the GF syntax for abstract expressions
+		 * and returns an object representing the expression. */
 		public static native Expr readExpr(String s) throws PGFError;
 
+		/** Compares the current expression with another expression by value. 
+		 * @return True if the expressions are equal. */
 		public native boolean equals(Expr e);
 
 		private static native String showExpr(long ref);
diff --git a/src/runtime/java/org/grammaticalframework/pgf/ExprProb.java b/src/runtime/java/org/grammaticalframework/pgf/ExprProb.java
index 99ef0a92c..f3ec4cd8f 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/ExprProb.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/ExprProb.java
@@ -2,6 +2,7 @@ package org.grammaticalframework.pgf;
 
 import java.io.Serializable;
 
+/** Simply a pair of an expression and a probability value. */
 public class ExprProb implements Serializable {
 	private static final long serialVersionUID = -3112602244416576742L;
 
@@ -18,10 +19,12 @@ public class ExprProb implements Serializable {
 		return new ExprProb(new Expr(pool, gr, expr), prob);
 	}
 	
+	/** Returns the expression. */
 	public Expr getExpr() {
 		return expr;
 	}
 
+	/** Returns the negative logarithmic probability. */
 	public double getProb() {
 		return prob;
 	}
diff --git a/src/runtime/java/org/grammaticalframework/pgf/FullFormEntry.java b/src/runtime/java/org/grammaticalframework/pgf/FullFormEntry.java
index cc67b47f2..bbd7da1df 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/FullFormEntry.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/FullFormEntry.java
@@ -2,6 +2,7 @@ package org.grammaticalframework.pgf;
 
 import java.util.List;
 
+/** This is the class for entries in the full-form lexicon of the grammar*/
 public class FullFormEntry {
 	private String form;
 	private double prob;
@@ -13,14 +14,17 @@ public class FullFormEntry {
 		this.analyses = analyses;
 	}
 
+	/** This is the word form. */
 	public String getForm() {
 		return form;
 	}
 
+	/** This is its negative logarithmic probability. */
 	public double getProb() {
 		return prob;
 	}
 
+	/** This is the list of possible morphological analyses. */
 	public List<MorphoAnalysis> getAnalyses() {
 		return analyses;
 	}
diff --git a/src/runtime/java/org/grammaticalframework/pgf/Hypo.java b/src/runtime/java/org/grammaticalframework/pgf/Hypo.java
index a0aced647..660b1843f 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/Hypo.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/Hypo.java
@@ -2,6 +2,10 @@ package org.grammaticalframework.pgf;
 
 public class Hypo {
 	public native boolean getBindType();
+	
+	/** The name of the bound variable or '_' if there is none */
 	public native String getVariable();
+	
+	/** The type for this hypothesis */
 	public native Type getType();
 }
diff --git a/src/runtime/java/org/grammaticalframework/pgf/MorphoAnalysis.java b/src/runtime/java/org/grammaticalframework/pgf/MorphoAnalysis.java
index b746daaf1..b5b6d8041 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/MorphoAnalysis.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/MorphoAnalysis.java
@@ -2,6 +2,9 @@ package org.grammaticalframework.pgf;
 
 import java.io.Serializable;
 
+/** The class represents a possible morphological analysis of
+ * a word from the lexicon in the grammar
+ */
 public class MorphoAnalysis implements Serializable {
 	private static final long serialVersionUID = 1L;
 
@@ -15,14 +18,17 @@ public class MorphoAnalysis implements Serializable {
 		this.prob  = prob;
 	}
 	
+	/** The lemma, i.e. the abstract function name in the lexicon. */
 	public String getLemma() {
 		return lemma;
 	}
 
+	/** The name of the slot in the inflection table for the lemma. */
 	public String getField() {
 		return field;
 	}
 
+	/** Returns the negative logarithmic probability. */
 	public double getProb() {
 		return prob;
 	}
diff --git a/src/runtime/java/org/grammaticalframework/pgf/NercLiteralCallback.java b/src/runtime/java/org/grammaticalframework/pgf/NercLiteralCallback.java
index f44fe5202..1d5491f64 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/NercLiteralCallback.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/NercLiteralCallback.java
@@ -3,6 +3,11 @@ package org.grammaticalframework.pgf;
 import java.util.Collections;
 import java.util.Iterator;
 
+/** A callback for recognizing names. A name is a sequence of tokens
+ * starting with capital letters. The callback constructs an expression
+ * which is an abstract function name, if the name is in the lexicon.
+ * If it is not then the result is (SymbPN (MkSymb "&lt;name&gt;")).
+ */
 public class NercLiteralCallback implements LiteralCallback {
 	private PGF pgf;
 	private Concr concr;
diff --git a/src/runtime/java/org/grammaticalframework/pgf/PGF.java b/src/runtime/java/org/grammaticalframework/pgf/PGF.java
index c08462b80..3d2368c9d 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/PGF.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/PGF.java
@@ -3,29 +3,59 @@ package org.grammaticalframework.pgf;
 import java.io.*;
 import java.util.*;
 
+/** This is the class for PGF grammars.*/
 public class PGF {
+	/** Reads a grammar with the specified file path.
+	 * @param path The path to the file.
+	 * @return an object representing the grammar in memory. */
 	public static native PGF readPGF(String path) throws FileNotFoundException;
-	
+
+	/** Reads a grammar from an input stream.
+	 * @param stream The stream from which to read the grammar
+	 * @return an object representing the grammar in memory. */
 	public static native PGF readPGF(InputStream stream);
 
+	/** Returns the name of the abstract syntax for the grammar */
 	public native String getAbstractName();
 
+	/** Returns a map from a name of a concrete syntax to 
+	 * a {@link Concr} object for the syntax. */
 	public native Map<String,Concr> getLanguages();
 
+	/** Returns a list of with all categories in the grammar */
 	public native List<String> getCategories();
 	
+	/** The name of the start category for the grammar. This is usually
+	 * specified with 'params startcat=&lt;cat&gt;'.
+	 */
 	public native String getStartCat();
 	
+	/** Returns a list of with all functions in the grammar. */
 	public native List<String> getFunctions();
 	
+	/** Returns a list of with all functions with a given return category.
+	 * @param cat The name of the return category. */
 	public native List<String> getFunctionsByCat(String cat);
 	
+	/** Returns the type of the function with the given name.
+	 * @param fun The name of the function.
+	 */
 	public native Type getFunctionType(String fun);
 
+	/** Returns an iterable over the set of all expression in
+	 * the given category. The expressions are enumerated in decreasing
+	 * probability order.
+	 */
 	public Iterable<ExprProb> generateAll(String startCat) {
 		return new Generator(this, startCat);
 	}
 
+	/** Normalizes an expression to its normal form by using the 'def'
+	 * rules in the grammar.
+	 * 
+	 * @param expr the original expression.
+	 * @return the normalized expression.
+	 */
 	public native Expr compute(Expr expr);
 
 	//////////////////////////////////////////////////////////////////
diff --git a/src/runtime/java/org/grammaticalframework/pgf/PGFError.java b/src/runtime/java/org/grammaticalframework/pgf/PGFError.java
index 4753c1189..7de24daf3 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/PGFError.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/PGFError.java
@@ -1,5 +1,6 @@
 package org.grammaticalframework.pgf;
 
+/** This exception is thrown when some grammatical operation fails. */
 public class PGFError extends RuntimeException {
 	private static final long serialVersionUID = -5098784200043861938L;
 
diff --git a/src/runtime/java/org/grammaticalframework/pgf/ParseError.java b/src/runtime/java/org/grammaticalframework/pgf/ParseError.java
index 950796352..7fd332708 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/ParseError.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/ParseError.java
@@ -1,5 +1,6 @@
 package org.grammaticalframework.pgf;
 
+/** This exception is thrown when parsing a string fails. */
 public class ParseError extends Exception {
 	private static final long serialVersionUID = -6086991674218306569L;
 
diff --git a/src/runtime/java/org/grammaticalframework/pgf/Pool.java b/src/runtime/java/org/grammaticalframework/pgf/Pool.java
index 3a39babdf..6c326b76f 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/Pool.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/Pool.java
@@ -1,6 +1,6 @@
 package org.grammaticalframework.pgf;
 
-public class Pool {
+class Pool {
 	final long ref;
 
 	public Pool(long ref) {
diff --git a/src/runtime/java/org/grammaticalframework/pgf/TokenProb.java b/src/runtime/java/org/grammaticalframework/pgf/TokenProb.java
index b064e747b..3e0c4c62c 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/TokenProb.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/TokenProb.java
@@ -1,5 +1,6 @@
 package org.grammaticalframework.pgf;
 
+/** Simply a pair of an expression and a probability value. */
 public class TokenProb {
 	private String tok;
 	private double prob;
@@ -9,10 +10,12 @@ public class TokenProb {
 		this.prob = prob;
 	}
 
+	/** Returns the token. */
 	public String getToken() {
 		return tok;
 	}
 
+	/** Returns the negative logarithmic probability. */
 	public double getProb() {
 		return prob;
 	}
diff --git a/src/runtime/java/org/grammaticalframework/pgf/Type.java b/src/runtime/java/org/grammaticalframework/pgf/Type.java
index db7a9888f..d6e75b2d7 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/Type.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/Type.java
@@ -1,8 +1,16 @@
 package org.grammaticalframework.pgf;
 
+/** A class for types in the abstract syntax of a grammar */
 public class Type {
+	/** The category */
 	public native String getCategory();
+	
+	/** An array of arguments for the category */
 	public native Expr[] getExprs();
+	
+	/** An array of hypotheses if this is a function type. 
+	 * If the represented type is A1 -&gt; A2 -&gt; ... An -&gt; B, then
+	 * the hypotheses represent the types in A1, A2 ... An. */
 	public native Hypo[] getHypos();
 	
 	//////////////////////////////////////////////////////////////////
diff --git a/src/runtime/java/org/grammaticalframework/pgf/UnknownLiteralCallback.java b/src/runtime/java/org/grammaticalframework/pgf/UnknownLiteralCallback.java
index 347c2e28a..7d4209aad 100644
--- a/src/runtime/java/org/grammaticalframework/pgf/UnknownLiteralCallback.java
+++ b/src/runtime/java/org/grammaticalframework/pgf/UnknownLiteralCallback.java
@@ -3,6 +3,9 @@ package org.grammaticalframework.pgf;
 import java.util.Collections;
 import java.util.Iterator;
 
+/** A callback for recognizing words that are not in the lexicon.
+ * For such words the callback returns the expression (MkSymb "&lt;word&gt;").
+ */
 public class UnknownLiteralCallback implements LiteralCallback {
 	private Concr concr;
 
diff --git a/src/runtime/java/org/grammaticalframework/sg/SG.java b/src/runtime/java/org/grammaticalframework/sg/SG.java
index 278dd8117..64dd6b511 100644
--- a/src/runtime/java/org/grammaticalframework/sg/SG.java
+++ b/src/runtime/java/org/grammaticalframework/sg/SG.java
@@ -3,32 +3,38 @@ package org.grammaticalframework.sg;
 import java.io.Closeable;
 import org.grammaticalframework.pgf.*;
 
+/** This class represents a connection to a semantic graph database.
+ * The semantic graph is a graph represented as a set of tripples
+ * of abstract expressions. The graph can be used for instance to store
+ * semantic information for entities in a GF grammar.
+ */
 public class SG implements Closeable {
-	/** Opens a new database file */
+	/** Opens a new database file. */
 	public static native SG openSG(String path) throws SGError;
 	
-	/** Closes an already opened database */
+	/** Closes an already opened database. */
 	public native void close() throws SGError;
 
-	/** Reads a triple in the format <expr,expr,expr> and returns it as an array */
+	/** Reads a triple in the format &lt;expr,expr,expr&gt; and returns it as an array. */
 	public static native Expr[] readTriple(String s) throws PGFError;
 
-	/** Simple triple queries. Each of the arguments subj, pred and obj
-	 * could be null. In that case the argument is interpreted as a wild card.
+	/** Simple triple queries.
+	 * Each of the arguments subj, pred and obj could be null. 
+	 * A null argument is interpreted as a wild card.
 	 * If one of the arguments is not null then only triples with matching values
 	 * will be retrieved.  
 	 * 
-	 * @return An iterator over the matching triples
+	 * @return An iterator over the matching triples.
 	 */
 	public native TripleResult queryTriple(Expr subj, Expr pred, Expr obj) throws SGError;
 
-	/** Start a new transaction */
+	/** Starts a new transaction. */
 	public native void beginTrans() throws SGError;
 	
-	/** Commits the transaction */
+	/** Commits the transaction. */
 	public native void commit() throws SGError;
 	
-	/** Rollbacks all changes made in the current transaction */
+	/** Rollbacks all changes made in the current transaction. */
 	public native void rollback() throws SGError;
 
 	/** Inserts a new triple.
diff --git a/src/runtime/java/org/grammaticalframework/sg/SGError.java b/src/runtime/java/org/grammaticalframework/sg/SGError.java
index 0de876bd4..8b03caab7 100644
--- a/src/runtime/java/org/grammaticalframework/sg/SGError.java
+++ b/src/runtime/java/org/grammaticalframework/sg/SGError.java
@@ -1,5 +1,7 @@
 package org.grammaticalframework.sg;
 
+/** This exception is thrown if an error occurs in the semantic graph.
+ */
 public class SGError extends RuntimeException {
 	private static final long serialVersionUID = -6098784400143861939L;
 
diff --git a/src/runtime/java/org/grammaticalframework/sg/TripleResult.java b/src/runtime/java/org/grammaticalframework/sg/TripleResult.java
index 406b5c9f0..5570fd93b 100644
--- a/src/runtime/java/org/grammaticalframework/sg/TripleResult.java
+++ b/src/runtime/java/org/grammaticalframework/sg/TripleResult.java
@@ -3,22 +3,35 @@ package org.grammaticalframework.sg;
 import java.io.Closeable;
 import org.grammaticalframework.pgf.Expr;
 
+/** This class is used to iterate over a list of triples.
+ * To move to the next triple, call {@link TripleResult#hasNext}.
+ * When you do not need the iterator anymore then call {@link TripleResult#close}
+ * to release the allocated resources.
+ */
 public class TripleResult implements Closeable {
 	public native boolean hasNext();
+	
+	/** Closes the iterator and releases the allocated resources. */
 	public native void close();
 
+	/** Each triple has an unique integer key. You can get the key for
+	 * the current triple by calling {@link TripleResult#getKey}.
+	 */
 	public long getKey() {
 		return key;
 	}
 
+	/** This is the first element of the current triple. */
 	public Expr getSubject() {
 		return subj;
 	}
 
+	/** This is the second element of the current triple. */
 	public Expr getPredicate() {
 		return pred;
 	}
 
+	/** This is the third element of the current triple. */
 	public Expr getObject() {
 		return obj;
 	}