cscore: Documentation cleanups (#1236)

Reformat the C++ documentation to use the normal comment style and
add doxygen grouping.

cscore/src/main/java/edu/wpi/cscore/AxisCamera.java

@@ -25,6 +25,7 @@ public class AxisCamera extends HttpCamera {
 
   /**
    * Create a source for an Axis IP camera.
+   *
    * @param name Source name (arbitrary unique identifier)
    * @param host Camera host IP or DNS name (e.g. "10.x.y.11")
    */
@@ -34,6 +35,7 @@ public class AxisCamera extends HttpCamera {
 
   /**
    * Create a source for an Axis IP camera.
+   *
    * @param name Source name (arbitrary unique identifier)
    * @param hosts Array of Camera host IPs/DNS names
    */

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

@@ -17,6 +17,7 @@ public class CvSink extends VideoSink {
    * Create a sink for accepting OpenCV images.
    * WaitForFrame() must be called on the created sink to get each new
    * image.
+   *
    * @param name Source name (arbitrary unique identifier)
    */
   public CvSink(String name) {
@@ -38,6 +39,7 @@ public class CvSink extends VideoSink {
 
   /**
    * Set sink description.
+   *
    * @param description Description
    */
   public void setDescription(String description) {
@@ -48,6 +50,7 @@ public class CvSink extends VideoSink {
    * 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.
+   *
    * @return Frame time, or 0 on error (call GetError() to obtain the error
    *         message)
    */
@@ -59,6 +62,7 @@ public class CvSink extends VideoSink {
    * 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.
+   *
    * @return Frame time, or 0 on error (call GetError() to obtain the error
    *         message); the frame time is in 1 us increments.
    */
@@ -69,6 +73,7 @@ public class CvSink extends VideoSink {
   /**
    * 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.
+   *
    * @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/cscore/CvSource.java

@@ -15,6 +15,7 @@ import org.opencv.core.Mat;
 public class CvSource extends VideoSource {
   /**
    * Create an OpenCV source.
+   *
    * @param name Source name (arbitrary unique identifier)
    * @param mode Video mode being generated
    */
@@ -28,6 +29,7 @@ public class CvSource extends VideoSource {
 
   /**
    * Create an OpenCV source.
+   *
    * @param name Source name (arbitrary unique identifier)
    * @param pixelFormat Pixel format
    * @param width width
@@ -40,9 +42,11 @@ public class CvSource extends VideoSource {
 
   /**
    * Put an OpenCV image and notify sinks.
-   * Only 8-bit single-channel or 3-channel (with BGR channel order) images
+   *
+   * <p>Only 8-bit single-channel or 3-channel (with BGR channel order) images
    * are supported. If the format, depth or channel order is different, use
    * Mat.convertTo() and/or cvtColor() to convert it first.
+   *
    * @param image OpenCV image
    */
   public void putFrame(Mat image) {
@@ -59,6 +63,7 @@ public class CvSource extends VideoSource {
 
   /**
    * Set source connection status.  Defaults to true.
+   *
    * @param connected True for connected, false for disconnected
    */
   public void setConnected(boolean connected) {
@@ -67,6 +72,7 @@ public class CvSource extends VideoSource {
 
   /**
    * Set source description.
+   *
    * @param description Description
    */
   public void setDescription(String description) {
@@ -75,6 +81,7 @@ public class CvSource extends VideoSource {
 
   /**
    * Create a property.
+   *
    * @param name Property name
    * @param kind Property kind
    * @param minimum Minimum value
@@ -104,6 +111,7 @@ public class CvSource extends VideoSource {
 
   /**
    * Create an integer property.
+   *
    * @param name Property name
    * @param minimum Minimum value
    * @param maximum Maximum value
@@ -131,6 +139,7 @@ public class CvSource extends VideoSource {
 
   /**
    * Create a boolean property.
+   *
    * @param name Property name
    * @param defaultValue Default value
    * @param value Current value
@@ -150,6 +159,7 @@ public class CvSource extends VideoSource {
 
   /**
    * Create a string property.
+   *
    * @param name Property name
    * @param value Current value
    * @return Property
@@ -170,6 +180,7 @@ public class CvSource extends VideoSource {
 
   /**
    * Configure enum property choices.
+   *
    * @param property Property
    * @param choices Choices
    */
@@ -179,6 +190,7 @@ public class CvSource extends VideoSource {
 
   /**
    * Configure enum property choices.
+   *
    * @param property Property
    * @param choices Choices
    * @deprecated Use {@code setEnumPropertyChoices} instead.

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

@@ -43,6 +43,7 @@ public class HttpCamera extends VideoCamera {
 
   /**
    * Create a source for a MJPEG-over-HTTP (IP) camera.
+   *
    * @param name Source name (arbitrary unique identifier)
    * @param url Camera URL (e.g. "http://10.x.y.11/video/stream.mjpg")
    */
@@ -52,6 +53,7 @@ public class HttpCamera extends VideoCamera {
 
   /**
    * Create a source for a MJPEG-over-HTTP (IP) camera.
+   *
    * @param name Source name (arbitrary unique identifier)
    * @param url Camera URL (e.g. "http://10.x.y.11/video/stream.mjpg")
    * @param kind Camera kind (e.g. kAxis)
@@ -62,6 +64,7 @@ public class HttpCamera extends VideoCamera {
 
   /**
    * Create a source for a MJPEG-over-HTTP (IP) camera.
+   *
    * @param name Source name (arbitrary unique identifier)
    * @param urls Array of Camera URLs
    */
@@ -71,6 +74,7 @@ public class HttpCamera extends VideoCamera {
 
   /**
    * Create a source for a MJPEG-over-HTTP (IP) camera.
+   *
    * @param name Source name (arbitrary unique identifier)
    * @param urls Array of Camera URLs
    * @param kind Camera kind (e.g. kAxis)
@@ -81,7 +85,8 @@ public class HttpCamera extends VideoCamera {
 
   /**
    * Get the kind of HTTP camera.
-   * Autodetection can result in returning a different value than the camera
+   *
+   * <p>Autodetection can result in returning a different value than the camera
    * was created with.
    */
   public HttpCameraKind getHttpCameraKind() {

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

@@ -13,6 +13,7 @@ package edu.wpi.cscore;
 public class MjpegServer extends VideoSink {
   /**
    * Create a MJPEG-over-HTTP server sink.
+   *
    * @param name Sink name (arbitrary unique identifier)
    * @param listenAddress TCP listen address (empty string for all addresses)
    * @param port TCP port number
@@ -23,6 +24,7 @@ public class MjpegServer extends VideoSink {
 
   /**
    * Create a MJPEG-over-HTTP server sink.
+   *
    * @param name Sink name (arbitrary unique identifier)
    * @param port TCP port number
    */

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

@@ -13,6 +13,7 @@ package edu.wpi.cscore;
 public class UsbCamera extends VideoCamera {
   /**
    * Create a source for a USB camera based on device number.
+   *
    * @param name Source name (arbitrary unique identifier)
    * @param dev Device number (e.g. 0 for /dev/video0)
    */
@@ -22,6 +23,7 @@ public class UsbCamera extends VideoCamera {
 
   /**
    * Create a source for a USB camera based on device path.
+   *
    * @param name Source name (arbitrary unique identifier)
    * @param path Path to device (e.g. "/dev/video0" on Linux)
    */
@@ -31,6 +33,7 @@ public class UsbCamera extends VideoCamera {
 
   /**
    * Enumerate USB cameras on the local system.
+   *
    * @return Vector of USB camera information (one for each camera)
    */
   public static UsbCameraInfo[] enumerateUsbCameras() {
@@ -46,6 +49,7 @@ public class UsbCamera extends VideoCamera {
 
   /**
    * Set how verbose the camera connection messages are.
+   *
    * @param level 0=don't display Connecting message, 1=do display message
    */
   void setConnectVerbose(int level) {

cscore/src/main/java/edu/wpi/cscore/UsbCameraInfo.java

@@ -13,6 +13,7 @@ package edu.wpi.cscore;
 public class UsbCameraInfo {
   /**
    * Create a new set of UsbCameraInfo.
+   *
    * @param dev Device number (e.g. N in '/dev/videoN' on Linux)
    * @param path Path to device if available (e.g. '/dev/video0' on Linux)
    * @param name Vendor/model name of the camera as provided by the USB driver

cscore/src/main/java/edu/wpi/cscore/VideoListener.java

@@ -16,6 +16,7 @@ import java.util.function.Consumer;
 public class VideoListener implements AutoCloseable {
   /**
    * Create an event listener.
+   *
    * @param listener Listener function
    * @param eventMask Bitmask of VideoEvent.Type values
    * @param immediateNotify Whether callback should be immediately called with

cscore/src/main/java/edu/wpi/cscore/VideoProperty.java

@@ -7,6 +7,9 @@
 
 package edu.wpi.cscore;
 
+/**
+ * A source or sink property.
+ */
 public class VideoProperty {
   public enum Kind {
     kNone(0), kBoolean(1), kInteger(2), kString(4), kEnum(8);

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

@@ -111,6 +111,7 @@ public class VideoSink implements AutoCloseable {
 
   /**
    * Get a property of the sink.
+   *
    * @param name Property name
    * @return Property (kind Property::kNone if no property with
    *         the given name exists)
@@ -136,6 +137,7 @@ public class VideoSink implements AutoCloseable {
    * Configure which source should provide frames to this sink.  Each sink
    * can accept frames from only a single source, but a single source can
    * provide frames to multiple clients.
+   *
    * @param source Source
    */
   public void setSource(VideoSource source) {
@@ -148,6 +150,7 @@ public class VideoSink implements AutoCloseable {
 
   /**
    * Get the connected source.
+   *
    * @return Connected source; nullptr if no source connected.
    */
   public VideoSource getSource() {
@@ -158,6 +161,7 @@ public class VideoSink implements AutoCloseable {
 
   /**
    * Get a property of the associated source.
+   *
    * @param name Property name
    * @return Property (kind Property::kNone if no property with
    *         the given name exists or no source connected)
@@ -169,6 +173,7 @@ public class VideoSink implements AutoCloseable {
 
   /**
    * Enumerate all existing sinks.
+   *
    * @return Vector of sinks.
    */
   @SuppressWarnings("PMD.AvoidInstantiatingObjectsInLoops")

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

@@ -127,6 +127,7 @@ public class VideoSource implements AutoCloseable {
 
   /**
    * Get a property.
+   *
    * @param name Property name
    * @return Property contents (of kind Property::kNone if no property with
    *         the given name exists)
@@ -169,6 +170,7 @@ public class VideoSource implements AutoCloseable {
 
   /**
    * Set the video mode.
+   *
    * @param pixelFormat desired pixel format
    * @param width desired width
    * @param height desired height
@@ -181,6 +183,7 @@ public class VideoSource implements AutoCloseable {
 
   /**
    * Set the pixel format.
+   *
    * @param pixelFormat desired pixel format
    * @return True if set successfully
    */
@@ -190,6 +193,7 @@ public class VideoSource implements AutoCloseable {
 
   /**
    * Set the resolution.
+   *
    * @param width desired width
    * @param height desired height
    * @return True if set successfully
@@ -200,6 +204,7 @@ public class VideoSource implements AutoCloseable {
 
   /**
    * Set the frames per second (FPS).
+   *
    * @param fps desired FPS
    * @return True if set successfully
    */
@@ -209,8 +214,10 @@ public class VideoSource implements AutoCloseable {
 
   /**
    * Get the actual FPS.
-   * CameraServerJNI#setTelemetryPeriod() must be called for this to be valid
+   *
+   * <p>CameraServerJNI#setTelemetryPeriod() must be called for this to be valid
    * (throws VisionException if telemetry is not enabled).
+   *
    * @return Actual FPS averaged over the telemetry period.
    */
   public double getActualFPS() {
@@ -220,8 +227,10 @@ public class VideoSource implements AutoCloseable {
 
   /**
    * Get the data rate (in bytes per second).
-   * CameraServerJNI#setTelemetryPeriod() must be called for this to be valid
+   *
+   * <p>CameraServerJNI#setTelemetryPeriod() must be called for this to be valid
    * (throws VisionException if telemetry is not enabled).
+   *
    * @return Data rate averaged over the telemetry period.
    */
   public double getActualDataRate() {
@@ -238,6 +247,7 @@ public class VideoSource implements AutoCloseable {
 
   /**
    * Enumerate all sinks connected to this source.
+   *
    * @return Vector of sinks.
    */
   @SuppressWarnings("PMD.AvoidInstantiatingObjectsInLoops")
@@ -252,6 +262,7 @@ public class VideoSource implements AutoCloseable {
 
   /**
    * Enumerate all existing sources.
+   *
    * @return Vector of sources.
    */
   @SuppressWarnings("PMD.AvoidInstantiatingObjectsInLoops")

cscore/src/main/native/include/cscore_c.h

@@ -22,20 +22,29 @@ extern "C" {
 
 struct CvMat;
 
-//
-// The C API is handle-based.  Sources and sinks are reference counted
-// internally to the library.  Any time a source or sink handle is returned
-// or provided to a callback, the reference count is incremented.
-// Calling CS_ReleaseSource() or CS_ReleaseSink() decrements the reference
-// count, and when the reference count reaches zero, the object is destroyed.
-// Connecting a source to a sink increments the reference count of the source,
-// and when the sink is destroyed (its reference count reaches zero), the
-// source reference count is decremented.
-//
+/**
+ * @defgroup cscore_c_api cscore C API
+ *
+ * Handle-based interface for C.
+ *
+ * <p>Sources and sinks are reference counted internally to the library.
+ * Any time a source or sink handle is returned or provided to a callback,
+ * the reference count is incremented.
+ *
+ * <p>Calling CS_ReleaseSource() or CS_ReleaseSink() decrements the reference
+ * count, and when the reference count reaches zero, the object is destroyed.
+ *
+ * <p>Connecting a source to a sink increments the reference count of the
+ * source, and when the sink is destroyed (its reference count reaches zero),
+ * the source reference count is decremented.
+ *
+ * @{
+ */
 
-//
-// Typedefs
-//
+/**
+ * @defgroup cscore_typedefs Typedefs
+ * @{
+ */
 typedef int CS_Bool;
 typedef int CS_Status;
 
@@ -44,10 +53,11 @@ typedef CS_Handle CS_Property;
 typedef CS_Handle CS_Listener;
 typedef CS_Handle CS_Sink;
 typedef CS_Handle CS_Source;
+/** @} */
 
-//
-// Status values
-//
+/**
+ * Status values
+ */
 enum CS_StatusValue {
   CS_PROPERTY_WRITE_FAILED = 2000,
   CS_OK = 0,
@@ -62,9 +72,9 @@ enum CS_StatusValue {
   CS_TELEMETRY_NOT_ENABLED = -2008
 };
 
-//
-// Logging levels
-//
+/**
+ * Logging levels
+ */
 enum CS_LogLevel {
   CS_LOG_CRITICAL = 50,
   CS_LOG_ERROR = 40,
@@ -77,9 +87,9 @@ enum CS_LogLevel {
   CS_LOG_DEBUG4 = 6
 };
 
-//
-// Pixel formats
-//
+/**
+ * Pixel formats
+ */
 enum CS_PixelFormat {
   CS_PIXFMT_UNKNOWN = 0,
   CS_PIXFMT_MJPEG,
@@ -89,9 +99,9 @@ enum CS_PixelFormat {
   CS_PIXFMT_GRAY
 };
 
-//
-// Frame formats
-//
+/**
+ * Video mode
+ */
 typedef struct CS_VideoMode {
   int pixelFormat;
   int width;
@@ -99,9 +109,9 @@ typedef struct CS_VideoMode {
   int fps;
 } CS_VideoMode;
 
-//
-// Property kinds
-//
+/**
+ * Property kinds
+ */
 enum CS_PropertyKind {
   CS_PROP_NONE = 0,
   CS_PROP_BOOLEAN = 1,
@@ -110,9 +120,9 @@ enum CS_PropertyKind {
   CS_PROP_ENUM = 8
 };
 
-//
-// Source kinds
-//
+/**
+ * Source kinds
+ */
 enum CS_SourceKind {
   CS_SOURCE_UNKNOWN = 0,
   CS_SOURCE_USB = 1,
@@ -120,9 +130,9 @@ enum CS_SourceKind {
   CS_SOURCE_CV = 4
 };
 
-//
-// HTTP Camera kinds
-//
+/**
+ * HTTP Camera kinds
+ */
 enum CS_HttpCameraKind {
   CS_HTTP_UNKNOWN = 0,
   CS_HTTP_MJPGSTREAMER = 1,
@@ -130,14 +140,14 @@ enum CS_HttpCameraKind {
   CS_HTTP_AXIS = 3
 };
 
-//
-// Sink kinds
-//
+/**
+ * Sink kinds
+ */
 enum CS_SinkKind { CS_SINK_UNKNOWN = 0, CS_SINK_MJPEG = 2, CS_SINK_CV = 4 };
 
-//
-// Listener event kinds
-//
+/**
+ * Listener event kinds
+ */
 enum CS_EventKind {
   CS_SOURCE_CREATED = 0x0001,
   CS_SOURCE_DESTROYED = 0x0002,
@@ -160,17 +170,17 @@ enum CS_EventKind {
   CS_SINK_PROPERTY_CHOICES_UPDATED = 0x40000
 };
 
-//
-// Telemetry kinds
-//
+/**
+ * Telemetry kinds
+ */
 enum CS_TelemetryKind {
   CS_SOURCE_BYTES_RECEIVED = 1,
   CS_SOURCE_FRAMES_RECEIVED = 2
 };
 
-//
-// Listener event
-//
+/**
+ * Listener event
+ */
 struct CS_Event {
   enum CS_EventKind kind;
 
@@ -191,9 +201,10 @@ struct CS_Event {
   const char* valueStr;
 };
 
-//
-// Property Functions
-//
+/**
+ * @defgroup cscore_property_cfunc Property Functions
+ * @{
+ */
 enum CS_PropertyKind CS_GetPropertyKind(CS_Property property,
                                         CS_Status* status);
 char* CS_GetPropertyName(CS_Property property, CS_Status* status);
@@ -208,10 +219,12 @@ void CS_SetStringProperty(CS_Property property, const char* value,
                           CS_Status* status);
 char** CS_GetEnumPropertyChoices(CS_Property property, int* count,
                                  CS_Status* status);
+/** @} */
 
-//
-// Source Creation Functions
-//
+/**
+ * @defgroup cscore_source_create_cfunc Source Creation Functions
+ * @{
+ */
 CS_Source CS_CreateUsbCameraDev(const char* name, int dev, CS_Status* status);
 CS_Source CS_CreateUsbCameraPath(const char* name, const char* path,
                                  CS_Status* status);
@@ -222,10 +235,12 @@ CS_Source CS_CreateHttpCameraMulti(const char* name, const char** urls,
                                    CS_Status* status);
 CS_Source CS_CreateCvSource(const char* name, const CS_VideoMode* mode,
                             CS_Status* status);
+/** @} */
 
-//
-// Source Functions
-//
+/**
+ * @defgroup cscore_source_cfunc Source Functions
+ * @{
+ */
 enum CS_SourceKind CS_GetSourceKind(CS_Source source, CS_Status* status);
 char* CS_GetSourceName(CS_Source source, CS_Status* status);
 char* CS_GetSourceDescription(CS_Source source, CS_Status* status);
@@ -255,10 +270,12 @@ CS_Sink* CS_EnumerateSourceSinks(CS_Source source, int* count,
                                  CS_Status* status);
 CS_Source CS_CopySource(CS_Source source, CS_Status* status);
 void CS_ReleaseSource(CS_Source source, CS_Status* status);
+/** @} */
 
-//
-// Camera Source Common Property Fuctions
-//
+/**
+ * @defgroup cscore_source_prop_cfunc Camera Source Common Property Fuctions
+ * @{
+ */
 void CS_SetCameraBrightness(CS_Source source, int brightness,
                             CS_Status* status);
 int CS_GetCameraBrightness(CS_Source source, CS_Status* status);
@@ -269,24 +286,30 @@ void CS_SetCameraWhiteBalanceManual(CS_Source source, int value,
 void CS_SetCameraExposureAuto(CS_Source source, CS_Status* status);
 void CS_SetCameraExposureHoldCurrent(CS_Source source, CS_Status* status);
 void CS_SetCameraExposureManual(CS_Source source, int value, CS_Status* status);
+/** @} */
 
-//
-// UsbCamera Source Functions
-//
+/**
+ * @defgroup cscore_usbcamera_cfunc UsbCamera Source Functions
+ * @{
+ */
 char* CS_GetUsbCameraPath(CS_Source source, CS_Status* status);
+/** @} */
 
-//
-// HttpCamera Source Functions
-//
+/**
+ * @defgroup cscore_httpcamera_cfunc HttpCamera Source Functions
+ * @{
+ */
 enum CS_HttpCameraKind CS_GetHttpCameraKind(CS_Source source,
                                             CS_Status* status);
 void CS_SetHttpCameraUrls(CS_Source source, const char** urls, int count,
                           CS_Status* status);
 char** CS_GetHttpCameraUrls(CS_Source source, int* count, CS_Status* status);
+/** @} */
 
-//
-// OpenCV Source Functions
-//
+/**
+ * @defgroup cscore_opencv_source_cfunc OpenCV Source Functions
+ * @{
+ */
 void CS_PutSourceFrame(CS_Source source, struct CvMat* image,
                        CS_Status* status);
 void CS_NotifySourceError(CS_Source source, const char* msg, CS_Status* status);
@@ -301,20 +324,24 @@ CS_Property CS_CreateSourceProperty(CS_Source source, const char* name,
 void CS_SetSourceEnumPropertyChoices(CS_Source source, CS_Property property,
                                      const char** choices, int count,
                                      CS_Status* status);
+/** @} */
 
-//
-// Sink Creation Functions
-//
+/**
+ * @defgroup cscore_sink_create_cfunc Sink Creation Functions
+ * @{
+ */
 CS_Sink CS_CreateMjpegServer(const char* name, const char* listenAddress,
                              int port, CS_Status* status);
 CS_Sink CS_CreateCvSink(const char* name, CS_Status* status);
 CS_Sink CS_CreateCvSinkCallback(const char* name, void* data,
                                 void (*processFrame)(void* data, uint64_t time),
                                 CS_Status* status);
+/** @} */
 
-//
-// Sink Functions
-//
+/**
+ * @defgroup cscore_sink_cfunc Sink Functions
+ * @{
+ */
 enum CS_SinkKind CS_GetSinkKind(CS_Sink sink, CS_Status* status);
 char* CS_GetSinkName(CS_Sink sink, CS_Status* status);
 char* CS_GetSinkDescription(CS_Sink sink, CS_Status* status);
@@ -328,16 +355,20 @@ CS_Property CS_GetSinkSourceProperty(CS_Sink sink, const char* name,
 CS_Source CS_GetSinkSource(CS_Sink sink, CS_Status* status);
 CS_Sink CS_CopySink(CS_Sink sink, CS_Status* status);
 void CS_ReleaseSink(CS_Sink sink, CS_Status* status);
+/** @} */
 
-//
-// MjpegServer Sink Functions
-//
+/**
+ * @defgroup cscore_mjpegserver_cfunc MjpegServer Sink Functions
+ * @{
+ */
 char* CS_GetMjpegServerListenAddress(CS_Sink sink, CS_Status* status);
 int CS_GetMjpegServerPort(CS_Sink sink, CS_Status* status);
+/** @} */
 
-//
-// OpenCV Sink Functions
-//
+/**
+ * @defgroup cscore_opencv_sink_cfunc OpenCV Sink Functions
+ * @{
+ */
 void CS_SetSinkDescription(CS_Sink sink, const char* description,
                            CS_Status* status);
 uint64_t CS_GrabSinkFrame(CS_Sink sink, struct CvMat* image, CS_Status* status);
@@ -345,10 +376,12 @@ uint64_t CS_GrabSinkFrameTimeout(CS_Sink sink, struct CvMat* image,
                                  double timeout, CS_Status* status);
 char* CS_GetSinkError(CS_Sink sink, CS_Status* status);
 void CS_SetSinkEnabled(CS_Sink sink, CS_Bool enabled, CS_Status* status);
+/** @} */
 
-//
-// Listener Functions
-//
+/**
+ * @defgroup cscore_listener_cfunc Listener Functions
+ * @{
+ */
 void CS_SetListenerOnStart(void (*onStart)(void* data), void* data);
 void CS_SetListenerOnExit(void (*onExit)(void* data), void* data);
 CS_Listener CS_AddListener(
@@ -356,30 +389,40 @@ CS_Listener CS_AddListener(
     int eventMask, int immediateNotify, CS_Status* status);
 
 void CS_RemoveListener(CS_Listener handle, CS_Status* status);
+/** @} */
 
 int CS_NotifierDestroyed(void);
 
-//
-// Telemetry Functions
-//
+/**
+ * @defgroup cscore_telemetry_cfunc Telemetry Functions
+ * @{
+ */
 void CS_SetTelemetryPeriod(double seconds);
 double CS_GetTelemetryElapsedTime(void);
 int64_t CS_GetTelemetryValue(CS_Handle handle, enum CS_TelemetryKind kind,
                              CS_Status* status);
 double CS_GetTelemetryAverageValue(CS_Handle handle, enum CS_TelemetryKind kind,
                                    CS_Status* status);
+/** @} */
 
-//
-// Logging Functions
-//
+/**
+ * @defgroup cscore_logging_cfunc Logging Functions
+ * @{
+ */
 typedef void (*CS_LogFunc)(unsigned int level, const char* file,
                            unsigned int line, const char* msg);
 void CS_SetLogger(CS_LogFunc func, unsigned int min_level);
 void CS_SetDefaultLogger(unsigned int min_level);
+/** @} */
 
-//
-// Utility Functions
-//
+/**
+ * @defgroup cscore_utility_cfunc Utility Functions
+ * @{
+ */
+
+/**
+ * USB camera infomation
+ */
 typedef struct CS_UsbCameraInfo {
   int dev;
   char* path;
@@ -406,6 +449,9 @@ char* CS_GetHostname();
 
 char** CS_GetNetworkInterfaces(int* count);
 void CS_FreeNetworkInterfaces(char** interfaces, int count);
+/** @} */
+
+/** @} */
 
 #ifdef __cplusplus
 }  // extern "C"

cscore/src/main/native/include/cscore_cpp.h

@@ -26,23 +26,31 @@ class Mat;
 
 namespace cs {
 
-//
-// Handle-based interface for C++.  Users are encouraged to use the
-// object oriented interface instead; this interface is intended for use
-// in applications such as JNI which require handle-based access.
-//
+/**
+ * @defgroup cscore_cpp_api cscore C++ function API
+ *
+ * Handle-based interface for C++.  Users are encouraged to use the
+ * object oriented interface instead; this interface is intended for use
+ * in applications such as JNI which require handle-based access.
+ *
+ * @{
+ */
 
-/// USB camera information
+/**
+ * USB camera information
+ */
 struct UsbCameraInfo {
-  /// Device number (e.g. N in '/dev/videoN' on Linux)
+  /** Device number (e.g. N in '/dev/videoN' on Linux) */
   int dev;
-  /// Path to device if available (e.g. '/dev/video0' on Linux)
+  /** Path to device if available (e.g. '/dev/video0' on Linux) */
   std::string path;
-  /// Vendor/model name of the camera as provided by the USB driver
+  /** Vendor/model name of the camera as provided by the USB driver */
   std::string name;
 };
 
-/// Video mode
+/**
+ * Video mode
+ */
 struct VideoMode : public CS_VideoMode {
   enum PixelFormat {
     kUnknown = CS_PIXFMT_UNKNOWN,
@@ -67,7 +75,9 @@ struct VideoMode : public CS_VideoMode {
   explicit operator bool() const { return pixelFormat == kUnknown; }
 };
 
-/// Listener event
+/**
+ * Listener event
+ */
 struct RawEvent {
   enum Kind {
     kSourceCreated = CS_SOURCE_CREATED,
@@ -136,9 +146,10 @@ struct RawEvent {
   std::string valueStr;
 };
 
-//
-// Property Functions
-//
+/**
+ * @defgroup cscore_property_func Property Functions
+ * @{
+ */
 CS_PropertyKind GetPropertyKind(CS_Property property, CS_Status* status);
 std::string GetPropertyName(CS_Property property, CS_Status* status);
 wpi::StringRef GetPropertyName(CS_Property property,
@@ -158,10 +169,12 @@ void SetStringProperty(CS_Property property, wpi::StringRef value,
                        CS_Status* status);
 std::vector<std::string> GetEnumPropertyChoices(CS_Property property,
                                                 CS_Status* status);
+/** @} */
 
-//
-// Source Creation Functions
-//
+/**
+ * @defgroup cscore_source_create_func Source Creation Functions
+ * @{
+ */
 CS_Source CreateUsbCameraDev(wpi::StringRef name, int dev, CS_Status* status);
 CS_Source CreateUsbCameraPath(wpi::StringRef name, wpi::StringRef path,
                               CS_Status* status);
@@ -171,10 +184,12 @@ CS_Source CreateHttpCamera(wpi::StringRef name, wpi::ArrayRef<std::string> urls,
                            CS_HttpCameraKind kind, CS_Status* status);
 CS_Source CreateCvSource(wpi::StringRef name, const VideoMode& mode,
                          CS_Status* status);
+/** @} */
 
-//
-// Source Functions
-//
+/**
+ * @defgroup cscore_source_func Source Functions
+ * @{
+ */
 CS_SourceKind GetSourceKind(CS_Source source, CS_Status* status);
 std::string GetSourceName(CS_Source source, CS_Status* status);
 wpi::StringRef GetSourceName(CS_Source source, wpi::SmallVectorImpl<char>& buf,
@@ -205,10 +220,12 @@ wpi::ArrayRef<CS_Sink> EnumerateSourceSinks(CS_Source source,
                                             CS_Status* status);
 CS_Source CopySource(CS_Source source, CS_Status* status);
 void ReleaseSource(CS_Source source, CS_Status* status);
+/** @} */
 
-//
-// Camera Source Common Property Fuctions
-//
+/**
+ * @defgroup cscore_camera_property_func Camera Source Common Property Fuctions
+ * @{
+ */
 void SetCameraBrightness(CS_Source source, int brightness, CS_Status* status);
 int GetCameraBrightness(CS_Source source, CS_Status* status);
 void SetCameraWhiteBalanceAuto(CS_Source source, CS_Status* status);
@@ -218,23 +235,29 @@ void SetCameraWhiteBalanceManual(CS_Source source, int value,
 void SetCameraExposureAuto(CS_Source source, CS_Status* status);
 void SetCameraExposureHoldCurrent(CS_Source source, CS_Status* status);
 void SetCameraExposureManual(CS_Source source, int value, CS_Status* status);
+/** @} */
 
-//
-// UsbCamera Source Functions
-//
+/**
+ * @defgroup cscore_usbcamera_func UsbCamera Source Functions
+ * @{
+ */
 std::string GetUsbCameraPath(CS_Source source, CS_Status* status);
+/** @} */
 
-//
-// HttpCamera Source Functions
-//
+/**
+ * @defgroup cscore_httpcamera_func HttpCamera Source Functions
+ * @{
+ */
 CS_HttpCameraKind GetHttpCameraKind(CS_Source source, CS_Status* status);
 void SetHttpCameraUrls(CS_Source source, wpi::ArrayRef<std::string> urls,
                        CS_Status* status);
 std::vector<std::string> GetHttpCameraUrls(CS_Source source, CS_Status* status);
+/** @} */
 
-//
-// OpenCV Source Functions
-//
+/**
+ * @defgroup cscore_opencv_source_func OpenCV Source Functions
+ * @{
+ */
 void PutSourceFrame(CS_Source source, cv::Mat& image, CS_Status* status);
 void NotifySourceError(CS_Source source, wpi::StringRef msg, CS_Status* status);
 void SetSourceConnected(CS_Source source, bool connected, CS_Status* status);
@@ -247,20 +270,24 @@ CS_Property CreateSourceProperty(CS_Source source, wpi::StringRef name,
 void SetSourceEnumPropertyChoices(CS_Source source, CS_Property property,
                                   wpi::ArrayRef<std::string> choices,
                                   CS_Status* status);
+/** @} */
 
-//
-// Sink Creation Functions
-//
+/**
+ * @defgroup cscore_sink_create_func Sink Creation Functions
+ * @{
+ */
 CS_Sink CreateMjpegServer(wpi::StringRef name, wpi::StringRef listenAddress,
                           int port, CS_Status* status);
 CS_Sink CreateCvSink(wpi::StringRef name, CS_Status* status);
 CS_Sink CreateCvSinkCallback(wpi::StringRef name,
                              std::function<void(uint64_t time)> processFrame,
                              CS_Status* status);
+/** @} */
 
-//
-// Sink Functions
-//
+/**
+ * @defgroup cscore_sink_func Sink Functions
+ * @{
+ */
 CS_SinkKind GetSinkKind(CS_Sink sink, CS_Status* status);
 std::string GetSinkName(CS_Sink sink, CS_Status* status);
 wpi::StringRef GetSinkName(CS_Sink sink, wpi::SmallVectorImpl<char>& buf,
@@ -278,16 +305,20 @@ CS_Property GetSinkSourceProperty(CS_Sink sink, wpi::StringRef name,
 CS_Source GetSinkSource(CS_Sink sink, CS_Status* status);
 CS_Sink CopySink(CS_Sink sink, CS_Status* status);
 void ReleaseSink(CS_Sink sink, CS_Status* status);
+/** @} */
 
-//
-// MjpegServer Sink Functions
-//
+/**
+ * @defgroup cscore_mjpegserver_func MjpegServer Sink Functions
+ * @{
+ */
 std::string GetMjpegServerListenAddress(CS_Sink sink, CS_Status* status);
 int GetMjpegServerPort(CS_Sink sink, CS_Status* status);
+/** @} */
 
-//
-// OpenCV Sink Functions
-//
+/**
+ * @defgroup cscore_opencv_sink_func OpenCV Sink Functions
+ * @{
+ */
 void SetSinkDescription(CS_Sink sink, wpi::StringRef description,
                         CS_Status* status);
 uint64_t GrabSinkFrame(CS_Sink sink, cv::Mat& image, CS_Status* status);
@@ -297,10 +328,12 @@ std::string GetSinkError(CS_Sink sink, CS_Status* status);
 wpi::StringRef GetSinkError(CS_Sink sink, wpi::SmallVectorImpl<char>& buf,
                             CS_Status* status);
 void SetSinkEnabled(CS_Sink sink, bool enabled, CS_Status* status);
+/** @} */
 
-//
-// Listener Functions
-//
+/**
+ * @defgroup cscore_listener_func Listener Functions
+ * @{
+ */
 void SetListenerOnStart(std::function<void()> onStart);
 void SetListenerOnExit(std::function<void()> onExit);
 
@@ -308,31 +341,37 @@ CS_Listener AddListener(std::function<void(const RawEvent& event)> callback,
                         int eventMask, bool immediateNotify, CS_Status* status);
 
 void RemoveListener(CS_Listener handle, CS_Status* status);
+/** @} */
 
 bool NotifierDestroyed();
 
-//
-// Telemetry Functions
-//
+/**
+ * @defgroup cscore_telemetry_func Telemetry Functions
+ * @{
+ */
 void SetTelemetryPeriod(double seconds);
 double GetTelemetryElapsedTime();
 int64_t GetTelemetryValue(CS_Handle handle, CS_TelemetryKind kind,
                           CS_Status* status);
 double GetTelemetryAverageValue(CS_Handle handle, CS_TelemetryKind kind,
                                 CS_Status* status);
+/** @} */
 
-//
-// Logging Functions
-//
+/**
+ * @defgroup cscore_logging_func Logging Functions
+ * @{
+ */
 typedef std::function<void(unsigned int level, const char* file,
                            unsigned int line, const char* msg)>
     LogFunc;
 void SetLogger(LogFunc func, unsigned int min_level);
 void SetDefaultLogger(unsigned int min_level);
+/** @} */
 
-//
-// Utility Functions
-//
+/**
+ * @defgroup cscore_utility_func Utility Functions
+ * @{
+ */
 std::vector<UsbCameraInfo> EnumerateUsbCameras(CS_Status* status);
 
 wpi::ArrayRef<CS_Source> EnumerateSourceHandles(
@@ -343,15 +382,24 @@ wpi::ArrayRef<CS_Sink> EnumerateSinkHandles(wpi::SmallVectorImpl<CS_Sink>& vec,
 std::string GetHostname();
 
 std::vector<std::string> GetNetworkInterfaces();
+/** @} */
+
+/** @} */
 
 }  // namespace cs
 
-// C functions taking a cv::Mat* for specific interop implementations
+/**
+ * @defgroup cscore_cpp_opencv_special cscore C functions taking a cv::Mat*
+ *
+ * These are needed for specific interop implementations.
+ * @{
+ */
 extern "C" {
 uint64_t CS_GrabSinkFrameCpp(CS_Sink sink, cv::Mat* image, CS_Status* status);
 uint64_t CS_GrabSinkFrameTimeoutCpp(CS_Sink sink, cv::Mat* image,
                                     double timeout, CS_Status* status);
 void CS_PutSourceFrameCpp(CS_Source source, cv::Mat* image, CS_Status* status);
 }  // extern "C"
+/** @} */
 
 #endif  // CSCORE_CSCORE_CPP_H_