Clean up javadoc

pom.xml

@@ -165,7 +165,13 @@
                     </execution>
                 </executions>
                 <configuration>
-                    <doclint>none</doclint>
+                    <!-- https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html -->
+                    <!-- https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html#additional-options-provided-by-the-standard-doclet -->
+                    <doclint>all,-missing</doclint>
+                    <quiet>true</quiet>
+                    <show>public</show>
+                    <nodeprecated>true</nodeprecated>
+                    <excludePackageNames>xyz.froud.jvisa_example,xyz.froud.jvisa_example.*</excludePackageNames>
                 </configuration>
             </plugin>
         </plugins>

src/main/java/xyz/froud/jvisa/JVisaLibrary.java

@@ -29,14 +29,18 @@
 import java.nio.ShortBuffer;
 
 /**
- * Documentation of the VISA functions can be found at https://www.ni.com/docs/en-US/bundle/ni-visa/page/ni-visa/help_file_title.html
- *
+ * JNI wrapper for {@code visa.h}.
+ * <p>
  * Location of visa.h: "C:\Program Files\IVI Foundation\VISA\Win64\Include\visa.h"
+ * <p>
+ * This file was autogenerated by <a href="http://jnaerator.googlecode.com/">JNAerator</a>, a tool
+ * written by <a href="http://ochafik.com/">Olivier Chafik</a> that
+ * <a href="http://code.google.com/p/jnaerator/wiki/CreditsAndLicense">uses a few opensource
+ * projects.</a>.
  *
- * JNA Wrapper for library <b>visa</b><br>
- * This file was autogenerated by <a href="http://jnaerator.googlecode.com/">JNAerator</a>,<br>
- * a tool written by <a href="http://ochafik.com/">Olivier Chafik</a> that <a href="http://code.google.com/p/jnaerator/wiki/CreditsAndLicense">uses a few opensource projects.</a>.<br>
- * For help, please visit <a href="http://nativelibs4java.googlecode.com/">NativeLibs4Java</a> , <a href="http://rococoa.dev.java.net/">Rococoa</a>, or <a href="http://jna.dev.java.net/">JNA</a>. public interface VisaLibrary extends StdCallLibrary {
+ * @see
+ * <a href="https://www.ni.com/docs/en-US/bundle/ni-visa/page/ni-visa/help_file_title.html">NI-VISA
+ * Help</a>
  */
 @SuppressWarnings("ALL")
 public interface JVisaLibrary extends Library {
@@ -1791,7 +1795,7 @@ public interface JVisaLibrary extends Library {
      * Original signature : <code>ViStatus viInstallHandler(ViSession, ViEventType, ViHndlr, ViAddr)</code><br>
      * <i>native declaration : visa.h:106</i>
      *
-     * @see http://zone.ni.com/reference/en-XX/help/370131S-01/ni-visa/queuingcallbackmechanismsamplecode/
+     * @see <a href="https://www.ni.com/docs/en-US/bundle/ni-visa/page/ni-visa/queuingcallbackmechanismsamplecode.html">Queuing and Callback Mechanism Sample Code</a>
      *
      *
      * @param vi handle for instrument session (NOT handle to resource manager)

src/main/java/xyz/froud/jvisa/JVisaResourceManager.java

@@ -185,6 +185,7 @@ public String[] findResources() throws JVisaException {
      *
      * @param filterExpression it says it's a regular expression but it's not. Use {@code "?*"} to match all resources.
      * <table>
+     *      <caption>Filter expression for resource discovery</caption>
      *     <tr>
      *         <th>Special Characters and Operators</th>
      *         <th>Meaning</th>
@@ -349,7 +350,6 @@ private String getMessageForErrorCode(NativeLong errorCodeToGetDescriptionFor) {
      * If the status code indicates an error, this method will get a human-readable message for the
      * error code and throw a JVisaException.
      *
-     * @param rm the resource manager used for this VISA session
      * @param errorCode the value returned by a JVisaLibrary call
      * @param cFunctionName name of the C function corresponding to the call to the native shared library (.dll or .so or .dylib file)
      * @throws JVisaException if the status code means the call failed

src/main/java/xyz/froud/jvisa/SerialFlowControl.java

@@ -5,6 +5,8 @@
 import java.util.stream.Stream;
 
 /**
+ * Flow control for a serial port.
+ *
  * @author Peter Froud
  * @see <a href="https://www.ni.com/docs/en-US/bundle/ni-visa/page/ni-visa/vi_attr_asrl_flow_cntrl.html">VI_ATTR_ASRL_FLOW_CNTRL</a>
  */

src/main/java/xyz/froud/jvisa/SerialParity.java

@@ -5,6 +5,8 @@
 import java.util.stream.Stream;
 
 /**
+ * Parity for a serial port.
+ *
  * @author Peter Froud
  * @see <a href="https://www.ni.com/docs/en-US/bundle/ni-visa/page/ni-visa/vi_attr_asrl_parity.html">VI_ATTR_ASRL_PARITY</a>
  */

src/main/java/xyz/froud/jvisa/SerialStopBits.java

@@ -5,6 +5,8 @@
 import java.util.stream.Stream;
 
 /**
+ * Stop bits for a serial port.
+ *
  * @author Peter Froud
  * @see <a href="https://www.ni.com/docs/en-US/bundle/ni-visa/page/ni-visa/vi_attr_asrl_stop_bits.html">VI_ATTR_ASRL_STOP_BITS</a>
  */

src/main/java/xyz/froud/jvisa/eventhandling/JVisaEventCallback.java

@@ -20,6 +20,8 @@
 import com.sun.jna.Pointer;
 
 /**
+ * Interface with a method which may be called asynchronously.
+ *
  * @see <a href="https://github.com/java-native-access/jna/blob/master/www/CallbacksAndClosures.md">Callbacks, Function Pointers and Closures</a><br>
  * @see <a href="https://github.com/java-native-access/jna/issues/830">How to receive callback from jna?</a>
  */

src/main/java/xyz/froud/jvisa/eventhandling/JVisaEventHandler.java

@@ -19,6 +19,8 @@
 import com.sun.jna.Pointer;
 
 /**
+ * Container for event type, callback, and user data.
+ * <p>
  * You (the programmer) must keep a reference to otherwise it will be garbage collected and the callback won't work.
  *
  * @see <a href="https://github.com/java-native-access/jna/blob/master/www/CallbacksAndClosures.md">Callbacks, Function Pointers and Closures</a>

src/main/java/xyz/froud/jvisa/eventhandling/package-info.java

@@ -1,37 +1,6 @@
 /**
- * <h1>JVisa - Java VISA Driver</h1>
- * <h2>Copyright 2014-2018 Günter Fuchs gfuchs@acousticmicroscopy.com.</h2>
- * <p>
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
- * <p>
- * <a href="http://www.apache.org/licenses/LICENSE-2.0">this link.</a>
- * <p>
- * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
- * </p>
+ * Incomplete implementation of Visa event handling.
  *
- * <p>
- * Modifications by Peter Froud, June 2018
- * </p>
- *
- * <p>
- * VISA (Virtual Instrument Software Architecture) is an API for communicating with test &amp; measurement instruments.
- * <p>
- * JVisa is a library for using VISA instruments in a Java program.
- * <p>
- * <a href="https://github.com/pfroud/JVisa">https://github.com/pfroud/JVisa</a>
- * </p>
- *
- * <p>
- * This package contains an incomplete implementation for Visa event handling.
- * </p>
- *
- * <p>
- * Table of contents for the VISA Events section in the NI-VISA manual <a href=http://zone.ni.com/reference/en-XX/help/370131S-01/TOC21.htm">http://zone.ni.com/reference/en-XX/help/370131S-01/TOC21.htm</a>
- * </p>
- *
- * @author Günter Fuchs
- * @author Peter Froud
- * @version 0.6
- * @since February 12, 2018
+ * @see <a href="https://www.ni.com/docs/en-US/bundle/ni-visa/page/ni-visa/visaevents.html">VISA Events</a>
  */
 package xyz.froud.jvisa.eventhandling;

src/main/java/xyz/froud/jvisa/package-info.java

@@ -1,36 +1,5 @@
 /**
- * <h1>JVisa - Java VISA Driver</h1>
- * <h2>Copyright 2014-2018 Günter Fuchs gfuchs@acousticmicroscopy.com.</h2>
- * <p>
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
- * <p>
- * <a href="http://www.apache.org/licenses/LICENSE-2.0">this link.</a>
- * <p>
- * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
- * </p>
+ * Java library for VISA (Virtual Instrument Software Architecture)
  *
- * <p>
- * Modifications by Peter Froud, June 2018
- * </p>
- *
- * <p>
- * VISA (Virtual Instrument Software Architecture) is an API for communicating with test &amp; measurement instruments.
- * <p>
- * JVisa is a library for using VISA instruments in a Java program.
- * <p>
- * <a href="https://github.com/pfroud/JVisa">https://github.com/pfroud/JVisa</a>
- * </p>
- *
- * <p>
- * This package is the low-level Java code to interface the the Visa native shared library (.dll or .so or .dylib file).
- * <p/>
- * <p>
- * To see a examples and higher-level abstractions, look in the {@code jvisa_example} package.
- * </p>
- *
- * @author Günter Fuchs
- * @author Peter Froud
- * @version 0.6
- * @since February 12, 2018
  */
 package xyz.froud.jvisa;

src/main/java/xyz/froud/jvisa_example/FindResourcesExample.java

@@ -22,7 +22,7 @@
 import xyz.froud.jvisa.JVisaResourceManager;
 
 /**
- * Example showing usage of JVisaResourceManager#findResources().
+ * Example showing usage of {@link JVisaResourceManager#findResources()}.
  *
  * @author Peter Froud
  */

src/main/java/xyz/froud/jvisa_example/IdentificationQueryExample.java

@@ -23,26 +23,24 @@
 import xyz.froud.jvisa.JVisaResourceManager;
 
 /**
- * <p>
- * Example showing how to search for instruments and send a query.</p>
+ * Example showing how to search for instruments and send a query.
  *
  * <p>
- * Here's what it does:</p>
+ * Here's what it does:
  *
  * <ol>
  *     <li>Opens the default resource manager</li>
  *     <li>Searches for VISA instruments</li>
- *     <li>If any are instruments are found, it does this for each instrument:</li>
+ *     <li>If any instruments are found, it does this for each instrument:
  *         <ol>
  *             <li>Opens the instrument</li>
  *             <li>Sends the *IDN? command and prints the response</li>
  *             <li>Closes the instrument</li>
  *         </ol>
+ *      </li>
  *     <li>Closes the resource manager</li>
  * </ol>
  *
- * <p>
- * This is a low-level example. To see how you could use higher-level classes, look at HighLevelExample.java.</p>
  *
  * @author Peter Froud
  */

src/main/java/xyz/froud/jvisa_example/SerialPortExample.java

@@ -7,6 +7,10 @@
 import xyz.froud.jvisa.SerialParity;
 import xyz.froud.jvisa.SerialStopBits;
 
+/**
+ * Shows how to set serial port parameters.
+ * @author Peter Froud
+ */
 public class SerialPortExample {
 
     public static void main(String[] args) throws JVisaException {

src/main/java/xyz/froud/jvisa_example/abstraction/package-info.java

@@ -1,34 +1,4 @@
 /**
- * <h1>JVisa - Java VISA Driver</h1>
- * <h2>Copyright Copyright 2018-2020 Peter Froud</h2>
- * <p>
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
- * <p>
- * <a href="http://www.apache.org/licenses/LICENSE-2.0">this link.</a>
- * <p>
- * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
- * </p>
- *
- * <p>
- * VISA (Virtual Instrument Software Architecture) is an API for communicating with test &amp; measurement instruments.
- * <p>
- * JVisa is a library for using VISA instruments in a Java program.
- * <p>
- * <a href="https://github.com/pfroud/JVisa">https://github.com/pfroud/JVisa</a>
- * </p>
- *
- * <p>
- * This package shows an example of how to make an abstracted class for a specific instrument, in this case a power supply.
- * </p>
- *
- * <p>
- * To see examples of how to use the classes {@code JVisaResourceManager} and {@code JVisaInstrument}, look at the {@code lowlevel} package.
- * </p>
- *
- * <p>
- * To see the low-level Java code which communicates with the native shared library (.dll or .so or .dylib file), look at the {@code jvisa} package.
- * </p>
- *
- * @author Peter Froud
+ * Shows an example of how to make an abstracted class for a specific instrument, in this case a power supply.
  */
 package xyz.froud.jvisa_example.abstraction;

src/main/java/xyz/froud/jvisa_example/package-info.java

@@ -1,34 +1,7 @@
 /**
- * <h1>JVisa - Java VISA Driver</h1>
- * <h2>Copyright Copyright 2018-2020 Peter Froud</h2>
- * <p>
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
- * <p>
- * <a href="http://www.apache.org/licenses/LICENSE-2.0">this link.</a>
- * <p>
- * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
- * </p>
- *
- * <p>
- * VISA (Virtual Instrument Software Architecture) is an API for communicating with test &amp; measurement instruments.
- * <p>
- * JVisa is a library for using VISA instruments in a Java program.
- * <p>
- * <a href="https://github.com/pfroud/JVisa">https://github.com/pfroud/JVisa</a>
- * </p>
- *
- * <p>
- * This package contains examples of how to use the classes {@code JVisaResourceManager} and {@code JVisaInstrument}.
- * </p>
- *
+ * Examples of how to use the classes {@code JVisaResourceManager} and {@code JVisaInstrument}.
  * <p>
  * The {@code abstraction} package shows how to make a high-level abstraction for a specific instrument, in this case a power supply.
- * </p>
- *
- * <p>
- * To see the Java code which communicates with the native shared library (.dll or .so or .dylib file), look at the {@code jvisa} package.
- * </p>
  *
- * @author Peter Froud
  */
 package xyz.froud.jvisa_example;

src/main/javadoc/overview.html

@@ -0,0 +1,7 @@
+<html
+<body>
+Java library for VISA (Virtual Instrument Software Architecture).
+<p>
+<a href="https://github.com/pfroud/JVisa">https://github.com/pfroud/JVisa</a>
+</body>
+</html>