Fix documentation warnings generated by JavaDoc (NFC) (#3428)

Some C++ Doxygen comments were updated to reflect any wording changes.

See `rg "(@return|@param \w+) TODO" | less` for list of incomplete docs.

cscore/src/main/java/edu/wpi/first/cscore/CameraServerCvJNI.java

@@ -42,7 +42,11 @@ public class CameraServerCvJNI {
     }
   }
 
-  /** Force load the library. */
+  /**
+   * Force load the library.
+   *
+   * @throws IOException if library load failed
+   */
   public static synchronized void forceLoad() throws IOException {
     if (libraryLoaded) {
       return;

cscore/src/main/java/edu/wpi/first/cscore/CameraServerJNI.java

@@ -43,7 +43,11 @@ public class CameraServerJNI {
     }
   }
 
-  /** Force load the library. */
+  /**
+   * Force load the library.
+   *
+   * @throws IOException if library load failed
+   */
   public static synchronized void forceLoad() throws IOException {
     if (libraryLoaded) {
       return;

cscore/src/main/java/edu/wpi/first/cscore/CvSink.java

@@ -38,6 +38,7 @@ public class CvSink extends ImageSink {
    * Wait for the next frame and get the image. Times out (returning 0) after 0.225 seconds. The
    * provided image will have three 3-bit channels stored in BGR order.
    *
+   * @param image Where to store the image.
    * @return Frame time, or 0 on error (call GetError() to obtain the error message)
    */
   public long grabFrame(Mat image) {
@@ -48,6 +49,8 @@ public class CvSink extends ImageSink {
    * Wait for the next frame and get the image. Times out (returning 0) after timeout seconds. The
    * provided image will have three 3-bit channels stored in BGR order.
    *
+   * @param image Where to store the image.
+   * @param timeout Retrieval timeout in seconds.
    * @return Frame time, or 0 on error (call GetError() to obtain the error message); the frame time
    *     is in 1 us increments.
    */
@@ -59,6 +62,7 @@ public class CvSink extends ImageSink {
    * Wait for the next frame and get the image. May block forever. The provided image will have
    * three 3-bit channels stored in BGR order.
    *
+   * @param image Where to store the image.
    * @return Frame time, or 0 on error (call GetError() to obtain the error message); the frame time
    *     is in 1 us increments.
    */

cscore/src/main/java/edu/wpi/first/cscore/HttpCamera.java

@@ -88,17 +88,27 @@ public class HttpCamera extends VideoCamera {
    * Get the kind of HTTP camera.
    *
    * <p>Autodetection can result in returning a different value than the camera was created with.
+   *
+   * @return The kind of HTTP camera.
    */
   public HttpCameraKind getHttpCameraKind() {
     return getHttpCameraKindFromInt(CameraServerJNI.getHttpCameraKind(m_handle));
   }
 
-  /** Change the URLs used to connect to the camera. */
+  /**
+   * Change the URLs used to connect to the camera.
+   *
+   * @param urls Array of Camera URLs
+   */
   public void setUrls(String[] urls) {
     CameraServerJNI.setHttpCameraUrls(m_handle, urls);
   }
 
-  /** Get the URLs used to connect to the camera. */
+  /**
+   * Get the URLs used to connect to the camera.
+   *
+   * @return Array of camera URLs.
+   */
   public String[] getUrls() {
     return CameraServerJNI.getHttpCameraUrls(m_handle);
   }

cscore/src/main/java/edu/wpi/first/cscore/ImageSink.java

@@ -18,7 +18,11 @@ public abstract class ImageSink extends VideoSink {
     CameraServerJNI.setSinkDescription(m_handle, description);
   }
 
-  /** Get error string. Call this if WaitForFrame() returns 0 to determine what the error is. */
+  /**
+   * Get error string. Call this if WaitForFrame() returns 0 to determine what the error is.
+   *
+   * @return Error string.
+   */
   public String getError() {
     return CameraServerJNI.getSinkError(m_handle);
   }
@@ -27,6 +31,8 @@ public abstract class ImageSink extends VideoSink {
    * Enable or disable getting new frames. Disabling will cause processFrame (for callback-based
    * CvSinks) to not be called and WaitForFrame() to not return. This can be used to save processor
    * resources when frames are not needed.
+   *
+   * @param enabled Enable to get new frames.
    */
   public void setEnabled(boolean enabled) {
     CameraServerJNI.setSinkEnabled(m_handle, enabled);

cscore/src/main/java/edu/wpi/first/cscore/ImageSource.java

@@ -12,6 +12,8 @@ public abstract class ImageSource extends VideoSource {
   /**
    * Signal sinks that an error has occurred. This should be called instead of NotifyFrame when an
    * error occurs.
+   *
+   * @param msg Error message.
    */
   public void notifyError(String msg) {
     CameraServerJNI.notifySourceError(m_handle, msg);

cscore/src/main/java/edu/wpi/first/cscore/MjpegServer.java

@@ -27,12 +27,20 @@ public class MjpegServer extends VideoSink {
     this(name, "", port);
   }
 
-  /** Get the listen address of the server. */
+  /**
+   * Get the listen address of the server.
+   *
+   * @return The listen address.
+   */
   public String getListenAddress() {
     return CameraServerJNI.getMjpegServerListenAddress(m_handle);
   }
 
-  /** Get the port number of the server. */
+  /**
+   * Get the port number of the server.
+   *
+   * @return The port number.
+   */
   public int getPort() {
     return CameraServerJNI.getMjpegServerPort(m_handle);
   }

cscore/src/main/java/edu/wpi/first/cscore/UsbCamera.java

@@ -35,17 +35,29 @@ public class UsbCamera extends VideoCamera {
     return CameraServerJNI.enumerateUsbCameras();
   }
 
-  /** Change the path to the device. */
+  /**
+   * Change the path to the device.
+   *
+   * @param path New device path.
+   */
   void setPath(String path) {
     CameraServerJNI.setUsbCameraPath(m_handle, path);
   }
 
-  /** Get the path to the device. */
+  /**
+   * Get the path to the device.
+   *
+   * @return The device path.
+   */
   public String getPath() {
     return CameraServerJNI.getUsbCameraPath(m_handle);
   }
 
-  /** Get the full camera information for the device. */
+  /**
+   * Get the full camera information for the device.
+   *
+   * @return The camera information.
+   */
   public UsbCameraInfo getInfo() {
     return CameraServerJNI.getUsbCameraInfo(m_handle);
   }

cscore/src/main/java/edu/wpi/first/cscore/VideoCamera.java

@@ -18,12 +18,20 @@ public class VideoCamera extends VideoSource {
     super(handle);
   }
 
-  /** Set the brightness, as a percentage (0-100). */
+  /**
+   * Set the brightness, as a percentage (0-100).
+   *
+   * @param brightness Brightness as a percentage (0-100).
+   */
   public synchronized void setBrightness(int brightness) {
     CameraServerJNI.setCameraBrightness(m_handle, brightness);
   }
 
-  /** Get the brightness, as a percentage (0-100). */
+  /**
+   * Get the brightness, as a percentage (0-100).
+   *
+   * @return The brightness as a percentage (0-100).
+   */
   public synchronized int getBrightness() {
     return CameraServerJNI.getCameraBrightness(m_handle);
   }
@@ -38,7 +46,11 @@ public class VideoCamera extends VideoSource {
     CameraServerJNI.setCameraWhiteBalanceHoldCurrent(m_handle);
   }
 
-  /** Set the white balance to manual, with specified color temperature. */
+  /**
+   * Set the white balance to manual, with specified color temperature.
+   *
+   * @param value The specified color temperature.
+   */
   public synchronized void setWhiteBalanceManual(int value) {
     CameraServerJNI.setCameraWhiteBalanceManual(m_handle, value);
   }
@@ -53,7 +65,11 @@ public class VideoCamera extends VideoSource {
     CameraServerJNI.setCameraExposureHoldCurrent(m_handle);
   }
 
-  /** Set the exposure to manual, as a percentage (0-100). */
+  /**
+   * Set the exposure to manual, as a percentage (0-100).
+   *
+   * @param value The exposure as a percentage (0-100).
+   */
   public synchronized void setExposureManual(int value) {
     CameraServerJNI.setCameraExposureManual(m_handle, value);
   }

cscore/src/main/java/edu/wpi/first/cscore/VideoMode.java

@@ -31,7 +31,14 @@ public class VideoMode {
     return m_pixelFormatValues[pixelFormat];
   }
 
-  /** Create a new video mode. */
+  /**
+   * Create a new video mode.
+   *
+   * @param pixelFormat The pixel format enum as an integer.
+   * @param width The image width in pixels.
+   * @param height The image height in pixels.
+   * @param fps The camera's frames per second.
+   */
   public VideoMode(int pixelFormat, int width, int height, int fps) {
     this.pixelFormat = getPixelFormatFromInt(pixelFormat);
     this.width = width;
@@ -39,7 +46,14 @@ public class VideoMode {
     this.fps = fps;
   }
 
-  /** Create a new video mode. */
+  /**
+   * Create a new video mode.
+   *
+   * @param pixelFormat The pixel format.
+   * @param width The image width in pixels.
+   * @param height The image height in pixels.
+   * @param fps The camera's frames per second.
+   */
   public VideoMode(PixelFormat pixelFormat, int width, int height, int fps) {
     this.pixelFormat = pixelFormat;
     this.width = width;

cscore/src/main/java/edu/wpi/first/cscore/VideoSink.java

@@ -83,7 +83,11 @@ public class VideoSink implements AutoCloseable {
     return m_handle;
   }
 
-  /** Get the kind of the sink. */
+  /**
+   * Get the kind of the sink.
+   *
+   * @return The kind of the sink.
+   */
   public Kind getKind() {
     return getKindFromInt(CameraServerJNI.getSinkKind(m_handle));
   }
@@ -91,12 +95,18 @@ public class VideoSink implements AutoCloseable {
   /**
    * Get the name of the sink. The name is an arbitrary identifier provided when the sink is
    * created, and should be unique.
+   *
+   * @return The name of the sink.
    */
   public String getName() {
     return CameraServerJNI.getSinkName(m_handle);
   }
 
-  /** Get the sink description. This is sink-kind specific. */
+  /**
+   * Get the sink description. This is sink-kind specific.
+   *
+   * @return The sink description.
+   */
   public String getDescription() {
     return CameraServerJNI.getSinkDescription(m_handle);
   }
@@ -111,7 +121,11 @@ public class VideoSink implements AutoCloseable {
     return new VideoProperty(CameraServerJNI.getSinkProperty(m_handle, name));
   }
 
-  /** Enumerate all properties of this sink. */
+  /**
+   * Enumerate all properties of this sink.
+   *
+   * @return List of properties.
+   */
   public VideoProperty[] enumerateProperties() {
     int[] handles = CameraServerJNI.enumerateSinkProperties(m_handle);
     VideoProperty[] rv = new VideoProperty[handles.length];

cscore/src/main/java/edu/wpi/first/cscore/VideoSource.java

@@ -113,7 +113,11 @@ public class VideoSource implements AutoCloseable {
     return m_handle;
   }
 
-  /** Get the kind of the source. */
+  /**
+   * Get the kind of the source.
+   *
+   * @return The kind of the source.
+   */
   public Kind getKind() {
     return getKindFromInt(CameraServerJNI.getSourceKind(m_handle));
   }
@@ -121,12 +125,18 @@ public class VideoSource implements AutoCloseable {
   /**
    * Get the name of the source. The name is an arbitrary identifier provided when the source is
    * created, and should be unique.
+   *
+   * @return The name of the source.
    */
   public String getName() {
     return CameraServerJNI.getSourceName(m_handle);
   }
 
-  /** Get the source description. This is source-kind specific. */
+  /**
+   * Get the source description. This is source-kind specific.
+   *
+   * @return The source description.
+   */
   public String getDescription() {
     return CameraServerJNI.getSourceDescription(m_handle);
   }
@@ -153,7 +163,11 @@ public class VideoSource implements AutoCloseable {
     CameraServerJNI.setSourceConnectionStrategy(m_handle, strategy.getValue());
   }
 
-  /** Returns if the source currently connected to whatever is providing the images. */
+  /**
+   * Returns true if the source currently connected to whatever is providing the images.
+   *
+   * @return True if the source currently connected to whatever is providing the images.
+   */
   public boolean isConnected() {
     return CameraServerJNI.isSourceConnected(m_handle);
   }
@@ -178,7 +192,11 @@ public class VideoSource implements AutoCloseable {
     return new VideoProperty(CameraServerJNI.getSourceProperty(m_handle, name));
   }
 
-  /** Enumerate all properties of this source. */
+  /**
+   * Enumerate all properties of this source.
+   *
+   * @return Array of video properties.
+   */
   public VideoProperty[] enumerateProperties() {
     int[] handles = CameraServerJNI.enumerateSourceProperties(m_handle);
     VideoProperty[] rv = new VideoProperty[handles.length];
@@ -188,7 +206,11 @@ public class VideoSource implements AutoCloseable {
     return rv;
   }
 
-  /** Get the current video mode. */
+  /**
+   * Get the current video mode.
+   *
+   * @return The current video mode.
+   */
   public VideoMode getVideoMode() {
     return CameraServerJNI.getSourceVideoMode(m_handle);
   }
@@ -197,6 +219,7 @@ public class VideoSource implements AutoCloseable {
    * Set the video mode.
    *
    * @param mode Video mode
+   * @return True if set successfully.
    */
   public boolean setVideoMode(VideoMode mode) {
     return CameraServerJNI.setSourceVideoMode(
@@ -312,7 +335,11 @@ public class VideoSource implements AutoCloseable {
         m_handle, CameraServerJNI.TelemetryKind.kSourceBytesReceived);
   }
 
-  /** Enumerate all known video modes for this source. */
+  /**
+   * Enumerate all known video modes for this source.
+   *
+   * @return Vector of video modes.
+   */
   public VideoMode[] enumerateVideoModes() {
     return CameraServerJNI.enumerateSourceVideoModes(m_handle);
   }

cscore/src/main/java/edu/wpi/first/cscore/raw/RawFrame.java

@@ -35,7 +35,16 @@ public class RawFrame implements AutoCloseable {
     CameraServerJNI.freeRawFrame(m_framePtr);
   }
 
-  /** Called from JNI to set data in class. */
+  /**
+   * Called from JNI to set data in class.
+   *
+   * @param dataByteBuffer A ByteBuffer pointing to the frame data.
+   * @param dataPtr A long (a char* in native code) pointing to the frame data.
+   * @param totalData The total length of the data stored in the frame.
+   * @param width The width of the frame.
+   * @param height The height of the frame.
+   * @param pixelFormat The PixelFormat of the frame.
+   */
   public void setData(
       ByteBuffer dataByteBuffer,
       long dataPtr,
@@ -51,7 +60,11 @@ public class RawFrame implements AutoCloseable {
     m_pixelFormat = pixelFormat;
   }
 
-  /** Get the pointer to native representation of this frame. */
+  /**
+   * Get the pointer to native representation of this frame.
+   *
+   * @return The pointer to native representation of this frame.
+   */
   public long getFramePtr() {
     return m_framePtr;
   }
@@ -60,6 +73,8 @@ public class RawFrame implements AutoCloseable {
    * Get a ByteBuffer pointing to the frame data. This ByteBuffer is backed by the frame directly.
    * Its lifetime is controlled by the frame. If a new frame gets read, it will overwrite the
    * current one.
+   *
+   * @return A ByteBuffer pointing to the frame data.
    */
   public ByteBuffer getDataByteBuffer() {
     return m_dataByteBuffer;
@@ -69,42 +84,72 @@ public class RawFrame implements AutoCloseable {
    * Get a long (is a char* in native code) pointing to the frame data. This pointer is backed by
    * the frame directly. Its lifetime is controlled by the frame. If a new frame gets read, it will
    * overwrite the current one.
+   *
+   * @return A long pointing to the frame data.
    */
   public long getDataPtr() {
     return m_dataPtr;
   }
 
-  /** Get the total length of the data stored in the frame. */
+  /**
+   * Get the total length of the data stored in the frame.
+   *
+   * @return The total length of the data stored in the frame.
+   */
   public int getTotalData() {
     return m_totalData;
   }
 
-  /** Get the width of the frame. */
+  /**
+   * Get the width of the frame.
+   *
+   * @return The width of the frame.
+   */
   public int getWidth() {
     return m_width;
   }
 
-  /** Set the width of the frame. */
+  /**
+   * Set the width of the frame.
+   *
+   * @param width The width of the frame.
+   */
   public void setWidth(int width) {
     this.m_width = width;
   }
 
-  /** Get the height of the frame. */
+  /**
+   * Get the height of the frame.
+   *
+   * @return The height of the frame.
+   */
   public int getHeight() {
     return m_height;
   }
 
-  /** Set the height of the frame. */
+  /**
+   * Set the height of the frame.
+   *
+   * @param height The height of the frame.
+   */
   public void setHeight(int height) {
     this.m_height = height;
   }
 
-  /** Get the PixelFormat of the frame. */
+  /**
+   * Get the PixelFormat of the frame.
+   *
+   * @return The PixelFormat of the frame.
+   */
   public int getPixelFormat() {
     return m_pixelFormat;
   }
 
-  /** Set the PixelFormat of the frame. */
+  /**
+   * Set the PixelFormat of the frame.
+   *
+   * @param pixelFormat The PixelFormat of the frame.
+   */
   public void setPixelFormat(int pixelFormat) {
     this.m_pixelFormat = pixelFormat;
   }

cscore/src/main/java/edu/wpi/first/cscore/raw/RawSink.java

@@ -28,6 +28,7 @@ public class RawSink extends ImageSink {
    * Wait for the next frame and get the image. Times out (returning 0) after 0.225 seconds. The
    * provided image will have three 8-bit channels stored in BGR order.
    *
+   * @param frame The frame object in which to store the image.
    * @return Frame time, or 0 on error (call getError() to obtain the error message); the frame time
    *     is in the same time base as wpi::Now(), and is in 1 us increments.
    */
@@ -39,6 +40,8 @@ public class RawSink extends ImageSink {
    * Wait for the next frame and get the image. Times out (returning 0) after timeout seconds. The
    * provided image will have three 8-bit channels stored in BGR order.
    *
+   * @param frame The frame object in which to store the image.
+   * @param timeout The frame timeout in seconds.
    * @return Frame time, or 0 on error (call getError() to obtain the error message); the frame time
    *     is in the same time base as wpi::Now(), and is in 1 us increments.
    */
@@ -50,6 +53,7 @@ public class RawSink extends ImageSink {
    * Wait for the next frame and get the image. May block forever. The provided image will have
    * three 8-bit channels stored in BGR order.
    *
+   * @param frame The frame object in which to store the image.
    * @return Frame time, or 0 on error (call getError() to obtain the error message); the frame time
    *     is in the same time base as wpi::Now(), and is in 1 us increments.
    */