doc: fix javadocs warnings when building via java 8

pgjdbc/src/main/java/org/postgresql/Driver.java

@@ -212,12 +212,12 @@ private Properties loadDefaultProperties() throws IOException {
      * character encoding , see
      * http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html
      * Note that you will probably want to have set up the Postgres database
-     * itself to use the same encoding, with the "-E <encoding>" argument
+     * itself to use the same encoding, with the {@code -E <encoding>} argument
      * to createdb.
      *
      * Our protocol takes the forms:
      * <PRE>
-     * jdbc:postgresql://host:port/database?param1=val1&...
+     * jdbc:postgresql://host:port/database?param1=val1&amp;...
      * </PRE>
      *
      * @param url the URL of the database to connect to
@@ -500,6 +500,8 @@ public int getMinorVersion()
     /**
      * Returns the server version series of this driver and the
      * specific build number.
+     *
+     * @return JDBC driver version
      */
     public static String getVersion()
     {
@@ -660,7 +662,7 @@ private static long timeout(Properties props)
         return (long) DriverManager.getLoginTimeout() * 1000;
     }
 
-    /*
+    /**
      * This method was added in v6.5, and simply throws an SQLException
      * for an unimplemented method. I decided to do it this way while
      * implementing the JDBC2 extensions to JDBC, as it should help keep the

pgjdbc/src/main/java/org/postgresql/PGConnection.java

@@ -24,24 +24,32 @@
      * since the last call to this method.
      * Returns null if there have been no notifications.
      * @since 7.3
+     * @throws SQLException if something wrong happens
+     * @return notifications that have been received
      */
     public PGNotification[] getNotifications() throws SQLException;
 
     /**
      * This returns the COPY API for the current connection.
      * @since 8.4
+     * @throws SQLException if something wrong happens
+     * @return COPY API for the current connection
      */
     public CopyManager getCopyAPI() throws SQLException;
 
     /**
      * This returns the LargeObject API for the current connection.
      * @since 7.3
+     * @throws SQLException if something wrong happens
+     * @return LargeObject API for the current connection
      */
     public LargeObjectManager getLargeObjectAPI() throws SQLException;
 
     /**
      * This returns the Fastpath API for the current connection.
      * @since 7.3
+     * @throws SQLException if something wrong happens
+     * @return Fastpath API for the current connection
      */
     public Fastpath getFastpathAPI() throws SQLException;
 
@@ -54,10 +62,12 @@
      *   {@link #addDataType(String,Class)}. This deprecated method does not
      *   work correctly for registering classes that cannot be directly loaded
      *   by the JDBC driver's classloader.
+     * @param type JDBC type name
+     * @param className class name
      * @throws RuntimeException if the type cannot be registered (class not
      *   found, etc).
      */
-    public void addDataType(String type, String name);
+    public void addDataType(String type, String className);
 
     /**
      * This allows client code to add a handler for one of org.postgresql's
@@ -67,7 +77,7 @@
      *
      * <p>The best way to use this is as follows:
      *
-     * <p><pre>
+     * <pre>
      * ...
      * ((org.postgresql.PGConnection)myconn).addDataType("mytype", my.class.name.class);
      * ...
@@ -143,7 +153,9 @@ public void addDataType(String type, Class klass)
      * Quotes are added only if necessary (i.e., if the string contains non-identifier characters or would be case-folded).
      * Embedded quotes are properly doubled.
      *
+     * @param identifier input identifier
      * @return the escaped identifier
+     * @throws SQLException if something goes wrong
      */
     public String escapeIdentifier(String identifier) throws SQLException;
 
@@ -152,7 +164,9 @@ public void addDataType(String type, Class klass)
      * Embedded single-quotes and backslashes are properly doubled.
      * Note that quote_literal returns null on null input.
      *
+     * @param literal input literal
      * @return the quoted literal
+     * @throws SQLException if something goes wrong
      */
     public String escapeLiteral(String literal) throws SQLException;
 }

pgjdbc/src/main/java/org/postgresql/PGNotification.java

@@ -14,12 +14,16 @@
 {
     /**
      * Returns name of this notification
+     *
+     * @return name of this notification
      * @since 7.3
      */
     public String getName();
 
     /**
      * Returns the process id of the backend process making this notification
+     *
+     * @return process id of the backend process making this notification
      * @since 7.3
      */
     public int getPID();
@@ -29,6 +33,7 @@
      * This feature has only been implemented in server versions 9.0
      * and later, so previous versions will always return an empty String.
      *
+     * @return additional information from the notifying process
      * @since 8.0
      */
     public String getParameter();

pgjdbc/src/main/java/org/postgresql/PGProperty.java

@@ -221,7 +221,7 @@
     ASSUME_MIN_SERVER_VERSION("assumeMinServerVersion", null, "Assume the server is at least that version"),
 
     /**
-     * The application name (require server version >= 9.0)
+     * The application name (require server version >= 9.0)
      */
     APPLICATION_NAME("ApplicationName", null, "name of the application (backend >= 9.0)"),
 
@@ -243,8 +243,8 @@
     /**
      * Force one of
      * <ul>
-     *   <li><acronym>SSPI</acronym> (Windows transparent single-sign-on)</li>
-     *   <li>GSSAPI</acronym> (Kerberos, via JSSE)
+     *   <li>SSPI (Windows transparent single-sign-on)</li>
+     *   <li>GSSAPI (Kerberos, via JSSE)</li>
      * </ul>
      * to be used when the server requests Kerberos or SSPI authentication.
      */
@@ -415,7 +415,7 @@ public int getInt(Properties properties) throws PSQLException
      * Return the {@code Integer} value for this connection parameter in the given {@code Properties}
      * @param properties properties to take actual value from
      * @return evaluated value for this connection parameter converted to Integer or null
-     * @throws PSQLException
+     * @throws PSQLException if unable to parse property as integer
      */
     public Integer getInteger(Properties properties) throws PSQLException
     {
@@ -459,6 +459,8 @@ public void set(Properties properties, int value)
 
     /**
      * Test whether this property is present in the given {@code Properties}
+     *
+     * @param properties set of properties to check current in
      * @return true if the parameter is specified in the given properties
      */
     public boolean isPresent(Properties properties)

pgjdbc/src/main/java/org/postgresql/PGResultSetMetaData.java

@@ -17,7 +17,10 @@
     /**
      * Returns the underlying column name of a query result, or ""
      * if it is unable to be determined.
-     * 
+     *
+     * @param column column position (1-based)
+     * @throws SQLException if something wrong happens
+     * @return underlying column name of a query result
      * @since 8.0
      */
     public String getBaseColumnName(int column) throws SQLException;
@@ -26,21 +29,30 @@
      * Returns the underlying table name of query result, or ""
      * if it is unable to be determined.
      *
+     * @param column column position (1-based)
+     * @throws SQLException if something wrong happens
+     * @return underlying table name of query result
      * @since 8.0
      */
     public String getBaseTableName(int column) throws SQLException;
 
     /**
-     * Returns the underlying table name of query result, or ""
+     * Returns the underlying schema name of query result, or ""
      * if it is unable to be determined.
      *
+     * @param column column position (1-based)
+     * @throws SQLException if something wrong happens
+     * @return underlying schema name of query result
      * @since 8.0
      */
     public String getBaseSchemaName(int column) throws SQLException;
 
     /**
      * Is a column Text or Binary?
      *
+     * @param column column position (1-based)
+     * @throws SQLException if something wrong happens
+     * @return if column is Text or Binary
      * @see Field#BINARY_FORMAT
      * @see Field#TEXT_FORMAT
      * @since 9.4

pgjdbc/src/main/java/org/postgresql/PGStatement.java

@@ -30,8 +30,10 @@
 
     /**
      * Returns the Last inserted/updated oid.
+     *
+     * @throws SQLException if something goes wrong
      * @return OID of last insert
-        * @since 7.3
+     * @since 7.3
      */
     public long getLastOID() throws SQLException;
 
@@ -41,8 +43,11 @@
      * As of build 302, this method is equivalent to
      *  <code>setPrepareThreshold(1)</code>.
      *
+     * @param flag use server prepare
+     * @throws SQLException if something goes wrong
+     *
      * @deprecated As of build 302, replaced by {@link #setPrepareThreshold(int)}
-        * @since 7.3
+     * @since 7.3
      */
     public void setUseServerPrepare(boolean flag) throws SQLException;
 

pgjdbc/src/main/java/org/postgresql/copy/CopyIn.java

@@ -29,6 +29,8 @@
      * pushed over in due time or when endCopy is called.  Some specific
      * modified server versions (Truviso) want this data sooner.
      * If you are unsure if you need to use this method, don't.
+     *
+     * @throws SQLException if the operation fails.
      */
     void flushCopy() throws SQLException;
 

pgjdbc/src/main/java/org/postgresql/core/BaseConnection.java

@@ -87,7 +87,6 @@
      *
      * @param ver the driver version to check
      * @return true if the driver's behavioural version is at least "ver".
-     * @throws SQLException if something goes wrong
      */
     @Deprecated
     public boolean haveMinimumCompatibleVersion(String ver);
@@ -100,10 +99,18 @@
      * overridden by the "compatible" URL parameter.
      *
      * The version is of the form xxyyzz, e.g. 90401 for PgJDBC 9.4.1.
+     * 
+     * This is used to toggle
+     * between different functionality as it changes across different releases
+     * of the jdbc driver code.  The values here are versions of the jdbc client
+     * and not server versions.  For example in 7.1 get/setBytes worked on
+     * LargeObject values, in 7.2 these methods were changed to work on bytea
+     * values. This change in functionality could be disabled by setting the
+     * "compatible" level to be 7.1, in which case the driver will revert to
+     * the 7.1 functionality.
      *
      * @param ver the driver version to check, eg 90401 for 9.4.1
      * @return true if the driver's behavioural version is at least "ver".
-     * @throws SQLException if something goes wrong
      */
     public boolean haveMinimumCompatibleVersion(int ver);
 
@@ -116,7 +123,6 @@
      *
      * @param ver the driver version to check
      * @return true if the driver's behavioural version is at least "ver".
-     * @throws SQLException if something goes wrong
      */
     public boolean haveMinimumCompatibleVersion(Version ver);
 
@@ -127,7 +133,6 @@
      *
      * @param ver the server version to check
      * @return true if the server version is at least "ver".
-     * @throws SQLException if something goes wrong
      */
     @Deprecated
     public boolean haveMinimumServerVersion(String ver);
@@ -140,7 +145,6 @@
      *
      * @param ver the server version to check, of the form xxyyzz eg 90401
      * @return true if the server version is at least "ver".
-     * @throws SQLException if something goes wrong
      */
     public boolean haveMinimumServerVersion(int ver);
 
@@ -152,7 +156,6 @@
      *
      * @param ver the server version to check
      * @return true if the server version is at least "ver".
-     * @throws SQLException if something goes wrong
      */
     public boolean haveMinimumServerVersion(Version ver);
 
@@ -184,7 +187,7 @@
      * standard or if it uses traditional PostgreSQL escaping rules. Versions
      * up to 8.1 always treated backslashes as escape characters in
      * string-literals. Since 8.2, this depends on the value of the
-     * <tt>standard_conforming_strings<tt> server variable.
+     * <tt>standard_conforming_strings</tt> server variable.
      * 
      * @return true if the server treats string literals according to the SQL
      *   standard
@@ -219,13 +222,18 @@
     public boolean binaryTransferSend(int oid);
 
     /**
-     *  Return whether to disable column name sanitization. 
+     * Return whether to disable column name sanitation.
+     *
+     * @return true column sanitizer is disabled
      */
     public boolean isColumnSanitiserDisabled();
 
     /**
-     *  Schedule a TimerTask for later execution.
-     *  The task will be scheduled with the shared Timer for this connection.
+     * Schedule a TimerTask for later execution.
+     * The task will be scheduled with the shared Timer for this connection.
+     *
+     * @param timerTask timer task to schedule
+     * @param milliSeconds delay in milliseconds
      */
     public void addTimerTask(TimerTask timerTask, long milliSeconds);
 

pgjdbc/src/main/java/org/postgresql/core/BaseStatement.java

@@ -45,6 +45,7 @@
      * @param p_sql the query to execute
      * @param flags additional {@link QueryExecutor} flags for execution; these
      *  are bitwise-ORed into the default flags.
+     * @return true if there is a result set
      * @throws SQLException if something goes wrong.
      */
     public boolean executeWithFlags(String p_sql, int flags) throws SQLException;
@@ -54,6 +55,7 @@
      *
      * @param flags additional {@link QueryExecutor} flags for execution; these
      *  are bitwise-ORed into the default flags.
+     * @return true if there is a result set
      * @throws SQLException if something goes wrong.
      */
     public boolean executeWithFlags(int flags) throws SQLException;

pgjdbc/src/main/java/org/postgresql/core/CachedQuery.java

@@ -15,7 +15,7 @@
  */
 public class CachedQuery implements CanEstimateSize {
     /**
-     * Cache key. {@link String} or {@link org.postgresql.jdbc.CallableQueryKey}.
+     * Cache key. {@link String} or {@code org.postgresql.jdbc.CallableQueryKey}.
      * It is assumed that {@code String.valueOf(key)*2} would give reasonable estimate of the number of retained bytes
      * by given key (see {@link #getSize}).
      */