docs: correct the Javadoc and enforce with Checkstyle (#1236)

pgjdbc/src/main/checkstyle/checks.xml

@@ -204,12 +204,12 @@
       <property name="allowSamelineMultipleAnnotations" value="true"/>
     </module>
     <module name="NonEmptyAtclauseDescription"/>
-    <!--<module name="JavadocTagContinuationIndentation"/>-->
+    <module name="JavadocTagContinuationIndentation"/>
     <!--Causes lots of "first sentence of javadoc is not followed by a period"-->
     <!--<module name="SummaryJavadoc">-->
     <!--<property name="forbiddenSummaryFragments" value="^@return the *|^This method returns |^A [{]@code [a-zA-Z0-9]+[}]( is a )"/>-->
     <!--</module>-->
-    <!--<module name="JavadocParagraph"/>-->
+    <module name="JavadocParagraph"/>
     <!--<module name="AtclauseOrder">-->
     <!--<property name="tagOrder" value="@param, @return, @throws, @deprecated"/>-->
     <!--<property name="target" value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF, METHOD_DEF, CTOR_DEF, VARIABLE_DEF"/>-->

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

@@ -38,21 +38,18 @@
 import java.util.logging.StreamHandler;
 
 /**
- * The Java SQL framework allows for multiple database drivers. Each driver should supply a class
- * that implements the Driver interface
+ * <p>The Java SQL framework allows for multiple database drivers. Each driver should supply a class
+ * that implements the Driver interface</p>
  *
- * <p>
- * The DriverManager will try to load as many drivers as it can find and then for any given
- * connection request, it will ask each driver in turn to try to connect to the target URL.
+ * <p>The DriverManager will try to load as many drivers as it can find and then for any given
+ * connection request, it will ask each driver in turn to try to connect to the target URL.</p>
  *
- * <p>
- * It is strongly recommended that each Driver class should be small and standalone so that the
- * Driver class can be loaded and queried without bringing in vast quantities of supporting code.
+ * <p>It is strongly recommended that each Driver class should be small and standalone so that the
+ * Driver class can be loaded and queried without bringing in vast quantities of supporting code.</p>
  *
- * <p>
- * When a Driver class is loaded, it should create an instance of itself and register it with the
+ * <p>When a Driver class is loaded, it should create an instance of itself and register it with the
  * DriverManager. This means that a user can load and register a driver by doing
- * Class.forName("foo.bah.Driver")
+ * Class.forName("foo.bah.Driver")</p>
  *
  * @see org.postgresql.PGConnection
  * @see java.sql.Driver
@@ -157,46 +154,48 @@ private Properties loadDefaultProperties() throws IOException {
   }
 
   /**
-   * Try to make a database connection to the given URL. The driver should return "null" if it
+   * <p>Try to make a database connection to the given URL. The driver should return "null" if it
    * realizes it is the wrong kind of driver to connect to the given URL. This will be common, as
    * when the JDBC driverManager is asked to connect to a given URL, it passes the URL to each
-   * loaded driver in turn.
+   * loaded driver in turn.</p>
    *
-   * <p>
-   * The driver should raise an SQLException if it is the right driver to connect to the given URL,
-   * but has trouble connecting to the database.
+   * <p>The driver should raise an SQLException if it is the right driver to connect to the given URL,
+   * but has trouble connecting to the database.</p>
    *
-   * <p>
-   * The java.util.Properties argument can be used to pass arbitrary string tag/value pairs as
-   * connection arguments.
+   * <p>The java.util.Properties argument can be used to pass arbitrary string tag/value pairs as
+   * connection arguments.</p>
    *
-   * user - (required) The user to connect as password - (optional) The password for the user ssl -
-   * (optional) Use SSL when connecting to the server readOnly - (optional) Set connection to
-   * read-only by default charSet - (optional) The character set to be used for converting to/from
+   * <ul>
+   * <li>user - (required) The user to connect as</li>
+   * <li>password - (optional) The password for the user</li>
+   * <li>ssl -(optional) Use SSL when connecting to the server</li>
+   * <li>readOnly - (optional) Set connection to read-only by default</li>
+   * <li>charSet - (optional) The character set to be used for converting to/from
    * the database to unicode. If multibyte is enabled on the server then the character set of the
    * database is used as the default, otherwise the jvm character encoding is used as the default.
-   * This value is only used when connecting to a 7.2 or older server. loglevel - (optional) Enable
-   * logging of messages from the driver. The value is an integer from 0 to 2 where: OFF = 0, INFO =
-   * 1, DEBUG = 2 The output is sent to DriverManager.getPrintWriter() if set, otherwise it is sent
-   * to System.out. compatible - (optional) This is used to toggle between different functionality
+   * This value is only used when connecting to a 7.2 or older server.</li>
+   * <li>loglevel - (optional) Enable logging of messages from the driver. The value is an integer
+   * from 0 to 2 where: OFF = 0, INFO =1, DEBUG = 2 The output is sent to
+   * DriverManager.getPrintWriter() if set, otherwise it is sent to System.out.</li>
+   * <li>compatible - (optional) 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.
+   * driver will revert to the 7.1 functionality.</li>
+   * </ul>
    *
-   * <p>
-   * Normally, at least "user" and "password" properties should be included in the properties. For a
+   * <p>Normally, at least "user" and "password" properties should be included in the properties. For a
    * list of supported 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
-   * {@code -E <encoding>} argument to createdb.
+   * {@code -E <encoding>} argument to createdb.</p>
    *
-   * Our protocol takes the forms:
+   * <p>Our protocol takes the forms:</p>
    *
-   * <PRE>
+   * <pre>
    *  jdbc:postgresql://host:port/database?param1=val1&amp;...
-   * </PRE>
+   * </pre>
    *
    * @param url the URL of the database to connect to
    * @param info a list of arbitrary tag/value pairs as connection arguments
@@ -285,9 +284,9 @@ public Connection connect(String url, Properties info) throws SQLException {
   private static String loggerHandlerFile;
 
   /**
-   * Setup java.util.logging.Logger using connection properties.
-   * <p>
-   * See {@link PGProperty#LOGGER_FILE} and {@link PGProperty#LOGGER_FILE}
+   * <p>Setup java.util.logging.Logger using connection properties.</p>
+   *
+   * <p>See {@link PGProperty#LOGGER_FILE} and {@link PGProperty#LOGGER_FILE}</p>
    *
    * @param props Connection Properties
    */
@@ -470,12 +469,11 @@ public boolean acceptsURL(String url) {
   }
 
   /**
-   * The getPropertyInfo method is intended to allow a generic GUI tool to discover what properties
-   * it should prompt a human for in order to get enough information to connect to a database.
+   * <p>The getPropertyInfo method is intended to allow a generic GUI tool to discover what properties
+   * it should prompt a human for in order to get enough information to connect to a database.</p>
    *
-   * <p>
-   * Note that depending on the values the human has supplied so far, additional values may become
-   * necessary, so it may be necessary to iterate through several calls to getPropertyInfo
+   * <p>Note that depending on the values the human has supplied so far, additional values may become
+   * necessary, so it may be necessary to iterate through several calls to getPropertyInfo</p>
    *
    * @param url the Url of the database to connect to
    * @param info a proposed list of tag/value pairs that will be sent on connect open.
@@ -522,20 +520,19 @@ public static String getVersion() {
   }
 
   /**
-   * Report whether the driver is a genuine JDBC compliant driver. A driver may only report "true"
+   * <p>Report whether the driver is a genuine JDBC compliant driver. A driver may only report "true"
    * here if it passes the JDBC compliance tests, otherwise it is required to return false. JDBC
-   * compliance requires full support for the JDBC API and full support for SQL 92 Entry Level.
+   * compliance requires full support for the JDBC API and full support for SQL 92 Entry Level.</p>
    *
-   * <p>
-   * For PostgreSQL, this is not yet possible, as we are not SQL92 compliant (yet).
+   * <p>For PostgreSQL, this is not yet possible, as we are not SQL92 compliant (yet).</p>
    */
   @Override
   public boolean jdbcCompliant() {
     return false;
   }
 
   /**
-   * Constructs a new DriverURL, splitting the specified URL into its component parts
+   * Constructs a new DriverURL, splitting the specified URL into its component parts.
    *
    * @param url JDBC URL to parse
    * @param defaults Default properties

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

@@ -112,25 +112,21 @@ public interface PGConnection {
   void addDataType(String type, String className);
 
   /**
-   * This allows client code to add a handler for one of org.postgresql's more unique data types.
+   * <p>This allows client code to add a handler for one of org.postgresql's more unique data types.</p>
    *
-   * <p>
-   * <b>NOTE:</b> This is not part of JDBC, but an extension.
+   * <p><b>NOTE:</b> This is not part of JDBC, but an extension.</p>
    *
-   * <p>
-   * The best way to use this is as follows:
+   * <p>The best way to use this is as follows:</p>
    *
    * <pre>
    * ...
    * ((org.postgresql.PGConnection)myconn).addDataType("mytype", my.class.name.class);
    * ...
    * </pre>
    *
-   * <p>
-   * where myconn is an open Connection to org.postgresql.
+   * <p>where myconn is an open Connection to org.postgresql.</p>
    *
-   * <p>
-   * The handling class must extend org.postgresql.util.PGobject
+   * <p>The handling class must extend org.postgresql.util.PGobject</p>
    *
    * @param type the PostgreSQL type to register
    * @param klass the class implementing the Java representation of the type; this class must
@@ -161,7 +157,7 @@ public interface PGConnection {
   int getPrepareThreshold();
 
   /**
-   * Set the default fetch size for statements created from this connection
+   * Set the default fetch size for statements created from this connection.
    *
    * @param fetchSize new default fetch size
    * @throws SQLException if specified negative <code>fetchSize</code> parameter
@@ -171,7 +167,7 @@ public interface PGConnection {
 
 
   /**
-   * Get the default fetch size for statements created from this connection
+   * Get the default fetch size for statements created from this connection.
    *
    * @return current state for default fetch size
    * @see PGProperty#DEFAULT_ROW_FETCH_SIZE
@@ -209,11 +205,11 @@ public interface PGConnection {
   String escapeLiteral(String literal) throws SQLException;
 
   /**
-   * Returns the query mode for this connection.
-   * <p>
-   * When running in simple query mode, certain features are not available: callable statements,
-   * partial result set fetch, bytea type, etc.
-   * The list of supported features is subject to change.
+   * <p>Returns the query mode for this connection.</p>
+   *
+   * <p>When running in simple query mode, certain features are not available: callable statements,
+   * partial result set fetch, bytea type, etc.</p>
+   * <p>The list of supported features is subject to change.</p>
    *
    * @return the preferred query mode
    * @see PreferQueryMode

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

@@ -6,19 +6,19 @@
 package org.postgresql;
 
 /**
- * This interface defines the public PostgreSQL extension for Notifications
+ * This interface defines the public PostgreSQL extension for Notifications.
  */
 public interface PGNotification {
   /**
-   * Returns name of this notification
+   * Returns name of this notification.
    *
    * @return name of this notification
    * @since 7.3
    */
   String getName();
 
   /**
-   * Returns the process id of the backend process making this notification
+   * Returns the process id of the backend process making this notification.
    *
    * @return process id of the backend process making this notification
    * @since 7.3