From 186e1dc54bdbf730fca5f61abbac24686c7e8510 Mon Sep 17 00:00:00 2001 From: Peter Johnson Date: Sat, 28 Jul 2018 17:41:57 -0700 Subject: [PATCH] ntcore: Documentation cleanups (#1237) --- .../first/networktables/ConnectionInfo.java | 1 + .../networktables/ConnectionNotification.java | 1 + .../wpi/first/networktables/EntryInfo.java | 2 + .../networktables/EntryNotification.java | 2 + .../wpi/first/networktables/LogMessage.java | 1 + .../wpi/first/networktables/NetworkTable.java | 16 +- .../networktables/NetworkTableEntry.java | 63 ++++++++ .../networktables/NetworkTableInstance.java | 20 +++ .../networktables/NetworkTableValue.java | 40 +++++ .../wpi/first/networktables/RpcAnswer.java | 4 + .../edu/wpi/first/networktables/RpcCall.java | 6 + .../networktables/EntryListenerFlags.h | 21 ++- .../include/networktables/NetworkTable.h | 48 +++++- .../include/networktables/NetworkTableEntry.h | 50 ++++++- .../networktables/NetworkTableInstance.h | 53 +++++-- .../include/networktables/NetworkTableType.h | 4 + .../include/networktables/NetworkTableValue.h | 55 ++++++- .../native/include/networktables/RpcCall.h | 11 +- .../networktables/TableEntryListener.h | 2 + .../include/networktables/TableListener.h | 2 + ntcore/src/main/native/include/ntcore_c.h | 137 ++++++++++++++++-- ntcore/src/main/native/include/ntcore_cpp.h | 123 ++++++++++++++-- 22 files changed, 607 insertions(+), 55 deletions(-) diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/ConnectionInfo.java b/ntcore/src/main/java/edu/wpi/first/networktables/ConnectionInfo.java index 5388ebebd5..b060f2f167 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/ConnectionInfo.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/ConnectionInfo.java @@ -46,6 +46,7 @@ public final class ConnectionInfo { /** Constructor. * This should generally only be used internally to NetworkTables. + * * @param remoteId Remote identifier * @param remoteIp Remote IP address * @param remotePort Remote port number diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/ConnectionNotification.java b/ntcore/src/main/java/edu/wpi/first/networktables/ConnectionNotification.java index a5efdcef08..129bf1a3f6 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/ConnectionNotification.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/ConnectionNotification.java @@ -31,6 +31,7 @@ public final class ConnectionNotification { /** Constructor. * This should generally only be used internally to NetworkTables. + * * @param inst Instance * @param listener Listener that was triggered * @param connected Connected if true diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/EntryInfo.java b/ntcore/src/main/java/edu/wpi/first/networktables/EntryInfo.java index ef4a328364..b516cc7257 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/EntryInfo.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/EntryInfo.java @@ -33,6 +33,7 @@ public final class EntryInfo { /** Constructor. * This should generally only be used internally to NetworkTables. + * * @param inst Instance * @param entry Entry handle * @param name Name @@ -58,6 +59,7 @@ public final class EntryInfo { /** * Get the entry as an object. + * * @return NetworkTableEntry for this entry. */ NetworkTableEntry getEntry() { diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/EntryNotification.java b/ntcore/src/main/java/edu/wpi/first/networktables/EntryNotification.java index f7c48d53fe..159b968747 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/EntryNotification.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/EntryNotification.java @@ -44,6 +44,7 @@ public final class EntryNotification { /** Constructor. * This should generally only be used internally to NetworkTables. + * * @param inst Instance * @param listener Listener that was triggered * @param entry Entry handle @@ -69,6 +70,7 @@ public final class EntryNotification { /** * Get the entry as an object. + * * @return NetworkTableEntry for this entry. */ public NetworkTableEntry getEntry() { diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/LogMessage.java b/ntcore/src/main/java/edu/wpi/first/networktables/LogMessage.java index e8c85c2d7f..2cf22ec8d2 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/LogMessage.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/LogMessage.java @@ -56,6 +56,7 @@ public final class LogMessage { /** Constructor. * This should generally only be used internally to NetworkTables. + * * @param inst Instance * @param logger Logger * @param level Log level diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTable.java b/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTable.java index d59dd212cd..1cd21bf1d1 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTable.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTable.java @@ -22,7 +22,6 @@ import java.util.function.Consumer; public final class NetworkTable { /** * The path separator for sub-tables and keys. - * */ public static final char PATH_SEPARATOR = '/'; @@ -33,6 +32,7 @@ public final class NetworkTable { /** * Gets the "base name" of a key. For example, "/foo/bar" becomes "bar". * If the key has a trailing slash, returns an empty string. + * * @param key key * @return base name */ @@ -95,6 +95,7 @@ public final class NetworkTable { * Gets a list of the names of all the super tables of a given key. For * example, the key "/foo/bar/baz" has a hierarchy of "/", "/foo", * "/foo/bar", and "/foo/bar/baz". + * * @param key the key * @return List of super tables */ @@ -128,6 +129,7 @@ public final class NetworkTable { /** * Gets the instance for the table. + * * @return Instance */ public NetworkTableInstance getInstance() { @@ -143,6 +145,7 @@ public final class NetworkTable { /** * Gets the entry for a sub key. + * * @param key the key name * @return Network table entry. */ @@ -157,6 +160,7 @@ public final class NetworkTable { /** * Listen to keys only within this table. + * * @param listener listener to add * @param flags {@link EntryListenerFlags} bitmask * @return Listener handle @@ -175,6 +179,7 @@ public final class NetworkTable { /** * Listen to a single key. + * * @param key the key name * @param listener listener to add * @param flags {@link EntryListenerFlags} bitmask @@ -188,6 +193,7 @@ public final class NetworkTable { /** * Remove an entry listener. + * * @param listener listener handle */ public void removeEntryListener(int listener) { @@ -198,6 +204,7 @@ public final class NetworkTable { * Listen for sub-table creation. * This calls the listener once for each newly created sub-table. * It immediately calls the listener for any existing sub-tables. + * * @param listener listener to add * @param localNotify notify local changes as well as remote * @return Listener handle @@ -233,6 +240,7 @@ public final class NetworkTable { /** * Remove a sub-table listener. + * * @param listener listener handle */ public void removeTableListener(int listener) { @@ -275,6 +283,7 @@ public final class NetworkTable { /** * Gets all keys in the table (not including sub-tables). + * * @param types bitmask of types; 0 is treated as a "don't care". * @return keys currently in the table */ @@ -297,6 +306,7 @@ public final class NetworkTable { /** * Gets all keys in the table (not including sub-tables). + * * @return keys currently in the table */ public Set getKeys() { @@ -305,6 +315,7 @@ public final class NetworkTable { /** * Gets the names of all subtables in the table. + * * @return subtables currently in the table */ public Set getSubTables() { @@ -344,6 +355,7 @@ public final class NetworkTable { /** * Gets the current value in the table, setting it if it does not exist. + * * @param key the key * @param defaultValue the default value to set if key doesn't exist. * @returns False if the table key exists with a different type @@ -372,6 +384,7 @@ public final class NetworkTable { /** * Save table values to a file. The file format used is identical to * that used for SavePersistent. + * * @param filename filename * @throws PersistentException if error saving file */ @@ -382,6 +395,7 @@ public final class NetworkTable { /** * Load table values from a file. The file format used is identical to * that used for SavePersistent / LoadPersistent. + * * @param filename filename * @return List of warnings (errors result in an exception instead) * @throws PersistentException if error saving file diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableEntry.java b/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableEntry.java index e73004f7cb..82d24dd068 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableEntry.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableEntry.java @@ -21,6 +21,7 @@ public final class NetworkTableEntry { /** * Construct from native handle. + * * @param inst Instance * @param handle Native handle */ @@ -31,6 +32,7 @@ public final class NetworkTableEntry { /** * Determines if the native handle is valid. + * * @return True if the native handle is valid, false otherwise. */ public boolean isValid() { @@ -39,6 +41,7 @@ public final class NetworkTableEntry { /** * Gets the native handle for the entry. + * * @return Native handle */ public int getHandle() { @@ -47,6 +50,7 @@ public final class NetworkTableEntry { /** * Gets the instance for the entry. + * * @return Instance */ public NetworkTableInstance getInstance() { @@ -55,6 +59,7 @@ public final class NetworkTableEntry { /** * Determines if the entry currently exists. + * * @return True if the entry exists, false otherwise. */ public boolean exists() { @@ -63,6 +68,7 @@ public final class NetworkTableEntry { /** * Gets the name of the entry (the key). + * * @return the entry's name */ public String getName() { @@ -71,6 +77,7 @@ public final class NetworkTableEntry { /** * Gets the type of the entry. + * * @return the entry's type */ public NetworkTableType getType() { @@ -79,6 +86,7 @@ public final class NetworkTableEntry { /** * Returns the flags. + * * @return the flags (bitmask) */ public int getFlags() { @@ -87,6 +95,7 @@ public final class NetworkTableEntry { /** * Gets the last time the entry's value was changed. + * * @return Entry last change time */ public long getLastChange() { @@ -95,6 +104,7 @@ public final class NetworkTableEntry { /** * Gets combined information about the entry. + * * @return Entry information */ public EntryInfo getInfo() { @@ -105,6 +115,7 @@ public final class NetworkTableEntry { * Gets the entry's value. * Returns a value with type NetworkTableType.kUnassigned if the value * does not exist. + * * @return the entry's value */ public NetworkTableValue getValue() { @@ -114,6 +125,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a boolean. If the entry does not exist or is of * different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -124,6 +136,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a double. If the entry does not exist or is of * different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -134,6 +147,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a double. If the entry does not exist or is of * different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -144,6 +158,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a string. If the entry does not exist or is of * different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -154,6 +169,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a raw value (byte array). If the entry does not * exist or is of different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -164,6 +180,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a boolean array. If the entry does not exist * or is of different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -174,6 +191,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a boolean array. If the entry does not exist * or is of different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -185,6 +203,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a double array. If the entry does not exist * or is of different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -195,6 +214,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a double array. If the entry does not exist * or is of different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -206,6 +226,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a double array. If the entry does not exist * or is of different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -217,6 +238,7 @@ public final class NetworkTableEntry { /** * Gets the entry's value as a string array. If the entry does not exist * or is of different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value */ @@ -226,6 +248,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type * @throws IllegalArgumentException if the value is not a known type @@ -282,6 +305,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -291,6 +315,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -300,6 +325,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -309,6 +335,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -318,6 +345,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -327,6 +355,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -336,6 +365,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -346,6 +376,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -355,6 +386,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -365,6 +397,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -374,6 +407,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value that will be assigned * @return False if the table key already exists with a different type * @throws IllegalArgumentException if the value is not a known type @@ -430,6 +464,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -439,6 +474,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -448,6 +484,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -457,6 +494,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -466,6 +504,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -475,6 +514,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @param len the length of the value * @return False if the entry exists with a different type @@ -491,6 +531,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -500,6 +541,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -509,6 +551,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -518,6 +561,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -527,6 +571,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -537,6 +582,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set * @throws IllegalArgumentException if the value is not a known type */ @@ -598,6 +644,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ public void forceSetBoolean(boolean value) { @@ -607,6 +654,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ public void forceSetDouble(double value) { @@ -616,6 +664,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ public void forceSetNumber(Number value) { @@ -625,6 +674,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ public void forceSetString(String value) { @@ -634,6 +684,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ public void forceSetRaw(byte[] value) { @@ -643,6 +694,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ public void forceSetBooleanArray(boolean[] value) { @@ -652,6 +704,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ public void forceSetBooleanArray(Boolean[] value) { @@ -661,6 +714,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ public void forceSetDoubleArray(double[] value) { @@ -670,6 +724,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ public void forceSetNumberArray(Number[] value) { @@ -679,6 +734,7 @@ public final class NetworkTableEntry { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ public void forceSetStringArray(String[] value) { @@ -687,6 +743,7 @@ public final class NetworkTableEntry { /** * Sets flags. + * * @param flags the flags to set (bitmask) */ public void setFlags(int flags) { @@ -695,6 +752,7 @@ public final class NetworkTableEntry { /** * Clears flags. + * * @param flags the flags to clear (bitmask) */ public void clearFlags(int flags) { @@ -717,6 +775,7 @@ public final class NetworkTableEntry { /** * Returns whether the value is persistent through program restarts. + * * @return True if the value is persistent. */ public boolean isPersistent() { @@ -734,6 +793,7 @@ public final class NetworkTableEntry { * Create a callback-based RPC entry point. Only valid to use on the server. * The callback function will be called when the RPC is called. * This function creates RPC version 0 definitions (raw data in and out). + * * @param callback callback function */ void createRpc(Consumer callback) { @@ -745,6 +805,7 @@ public final class NetworkTableEntry { * This function is non-blocking. Either {@link RpcCall#getResult()} or * {@link RpcCall#cancelResult()} must be called on the return value to either * get or ignore the result of the call. + * * @param params parameter * @return RPC call object. */ @@ -754,6 +815,7 @@ public final class NetworkTableEntry { /** * Add a listener for changes to the entry. + * * @param listener the listener to add * @param flags bitmask specifying desired notifications * @return listener handle @@ -764,6 +826,7 @@ public final class NetworkTableEntry { /** * Remove a listener from receiving entry events. + * * @param listener the listener to be removed */ public void removeListener(int listener) { diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableInstance.java b/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableInstance.java index e468944732..2564f70ab6 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableInstance.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableInstance.java @@ -52,6 +52,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Construct from native handle. + * * @param handle Native handle */ private NetworkTableInstance(int handle) { @@ -76,6 +77,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Determines if the native handle is valid. + * * @return True if the native handle is valid, false otherwise. */ public boolean isValid() { @@ -87,6 +89,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Get global default instance. + * * @return Global default instance */ public static synchronized NetworkTableInstance getDefault() { @@ -100,6 +103,7 @@ public final class NetworkTableInstance implements AutoCloseable { * Create an instance. * Note: A reference to the returned instance must be retained to ensure the * instance is not garbage collected. + * * @return Newly created instance */ public static NetworkTableInstance create() { @@ -110,6 +114,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Gets the native handle for the entry. + * * @return Native handle */ public int getHandle() { @@ -118,6 +123,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Gets the entry for a key. + * * @param name Key * @return Network table entry. */ @@ -330,6 +336,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Remove an entry listener. + * * @param listener Listener handle to remove */ public void removeEntryListener(int listener) { @@ -341,6 +348,7 @@ public final class NetworkTableInstance implements AutoCloseable { * for deterministic testing. This blocks until either the entry listener * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely * @return False if timed out, otherwise true. @@ -465,6 +473,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Remove a connection listener. + * * @param listener Listener handle to remove */ public void removeConnectionListener(int listener) { @@ -482,6 +491,7 @@ public final class NetworkTableInstance implements AutoCloseable { * for deterministic testing. This blocks until either the connection listener * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely * @return False if timed out, otherwise true. @@ -590,6 +600,7 @@ public final class NetworkTableInstance implements AutoCloseable { * Create a callback-based RPC entry point. Only valid to use on the server. * The callback function will be called when the RPC is called. * This function creates RPC version 0 definitions (raw data in and out). + * * @param entry the entry * @param callback callback function */ @@ -612,6 +623,7 @@ public final class NetworkTableInstance implements AutoCloseable { * for deterministic testing. This blocks until either the RPC call * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely * @return False if timed out, otherwise true. @@ -652,6 +664,7 @@ public final class NetworkTableInstance implements AutoCloseable { * Set the network identity of this node. * This is the name used during the initial connection handshake, and is * visible through ConnectionInfo on the remote node. + * * @param name identity to advertise */ public void setNetworkIdentity(String name) { @@ -660,6 +673,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Get the current network mode. + * * @return Bitmask of NetworkMode. */ public int getNetworkMode() { @@ -934,6 +948,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Gets information on the currently established network connections. * If operating as a client, this will return either zero or one values. + * * @return array of connection information */ public ConnectionInfo[] getConnections() { @@ -942,6 +957,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Return whether or not the instance is connected to another node. + * * @return True if connected. */ public boolean isConnected() { @@ -972,6 +988,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Save table values to a file. The file format used is identical to * that used for SavePersistent. + * * @param filename filename * @param prefix save only keys starting with this prefix * @throws PersistentException if error saving file @@ -983,6 +1000,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Load table values from a file. The file format used is identical to * that used for SavePersistent / LoadPersistent. + * * @param filename filename * @param prefix load only keys starting with this prefix * @return List of warnings (errors result in an exception instead) @@ -1074,6 +1092,7 @@ public final class NetworkTableInstance implements AutoCloseable { /** * Remove a logger. + * * @param logger Logger handle to remove */ public void removeLogger(int logger) { @@ -1091,6 +1110,7 @@ public final class NetworkTableInstance implements AutoCloseable { * for deterministic testing. This blocks until either the log event * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely * @return False if timed out, otherwise true. diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableValue.java b/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableValue.java index 4b6f0c8251..ebf88662ce 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableValue.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableValue.java @@ -29,6 +29,7 @@ public final class NetworkTableValue { /** * Get the data type. + * * @return The type. */ public NetworkTableType getType() { @@ -37,6 +38,7 @@ public final class NetworkTableValue { /** * Get the data value stored. + * * @return The type. */ public Object getValue() { @@ -45,6 +47,7 @@ public final class NetworkTableValue { /** * Get the creation time of the value. + * * @return The time, in the units returned by NetworkTablesJNI.now(). */ public long getTime() { @@ -57,6 +60,7 @@ public final class NetworkTableValue { /** * Determine if entry value contains a value or is unassigned. + * * @return True if the entry value contains a value. */ public boolean isValid() { @@ -65,6 +69,7 @@ public final class NetworkTableValue { /** * Determine if entry value contains a boolean. + * * @return True if the entry value is of boolean type. */ public boolean isBoolean() { @@ -73,6 +78,7 @@ public final class NetworkTableValue { /** * Determine if entry value contains a double. + * * @return True if the entry value is of double type. */ public boolean isDouble() { @@ -81,6 +87,7 @@ public final class NetworkTableValue { /** * Determine if entry value contains a string. + * * @return True if the entry value is of string type. */ public boolean isString() { @@ -89,6 +96,7 @@ public final class NetworkTableValue { /** * Determine if entry value contains a raw. + * * @return True if the entry value is of raw type. */ public boolean isRaw() { @@ -97,6 +105,7 @@ public final class NetworkTableValue { /** * Determine if entry value contains a rpc definition. + * * @return True if the entry value is of rpc definition type. */ public boolean isRpc() { @@ -105,6 +114,7 @@ public final class NetworkTableValue { /** * Determine if entry value contains a boolean array. + * * @return True if the entry value is of boolean array type. */ public boolean isBooleanArray() { @@ -113,6 +123,7 @@ public final class NetworkTableValue { /** * Determine if entry value contains a double array. + * * @return True if the entry value is of double array type. */ public boolean isDoubleArray() { @@ -121,6 +132,7 @@ public final class NetworkTableValue { /** * Determine if entry value contains a string array. + * * @return True if the entry value is of string array type. */ public boolean isStringArray() { @@ -133,6 +145,7 @@ public final class NetworkTableValue { /** * Get the entry's boolean value. + * * @return The boolean value. * @throws ClassCastException if the entry value is not of boolean type. */ @@ -145,6 +158,7 @@ public final class NetworkTableValue { /** * Get the entry's double value. + * * @return The double value. * @throws ClassCastException if the entry value is not of double type. */ @@ -157,6 +171,7 @@ public final class NetworkTableValue { /** * Get the entry's string value. + * * @return The string value. * @throws ClassCastException if the entry value is not of string type. */ @@ -169,6 +184,7 @@ public final class NetworkTableValue { /** * Get the entry's raw value. + * * @return The raw value. * @throws ClassCastException if the entry value is not of raw type. */ @@ -181,6 +197,7 @@ public final class NetworkTableValue { /** * Get the entry's rpc definition value. + * * @return The rpc definition value. * @throws ClassCastException if the entry value is not of rpc definition type. */ @@ -193,6 +210,7 @@ public final class NetworkTableValue { /** * Get the entry's boolean array value. + * * @return The boolean array value. * @throws ClassCastException if the entry value is not of boolean array type. */ @@ -205,6 +223,7 @@ public final class NetworkTableValue { /** * Get the entry's double array value. + * * @return The double array value. * @throws ClassCastException if the entry value is not of double array type. */ @@ -217,6 +236,7 @@ public final class NetworkTableValue { /** * Get the entry's string array value. + * * @return The string array value. * @throws ClassCastException if the entry value is not of string array type. */ @@ -233,6 +253,7 @@ public final class NetworkTableValue { /** * Creates a boolean entry value. + * * @param value the value * @return The entry value */ @@ -242,6 +263,7 @@ public final class NetworkTableValue { /** * Creates a boolean entry value. + * * @param value the value * @param time the creation time to use (instead of the current time) * @return The entry value @@ -252,6 +274,7 @@ public final class NetworkTableValue { /** * Creates a double entry value. + * * @param value the value * @return The entry value */ @@ -261,6 +284,7 @@ public final class NetworkTableValue { /** * Creates a double entry value. + * * @param value the value * @param time the creation time to use (instead of the current time) * @return The entry value @@ -271,6 +295,7 @@ public final class NetworkTableValue { /** * Creates a string entry value. + * * @param value the value * @return The entry value */ @@ -280,6 +305,7 @@ public final class NetworkTableValue { /** * Creates a string entry value. + * * @param value the value * @param time the creation time to use (instead of the current time) * @return The entry value @@ -290,6 +316,7 @@ public final class NetworkTableValue { /** * Creates a raw entry value. + * * @param value the value * @return The entry value */ @@ -299,6 +326,7 @@ public final class NetworkTableValue { /** * Creates a raw entry value. + * * @param value the value * @param time the creation time to use (instead of the current time) * @return The entry value @@ -309,6 +337,7 @@ public final class NetworkTableValue { /** * Creates a rpc entry value. + * * @param value the value * @return The entry value */ @@ -318,6 +347,7 @@ public final class NetworkTableValue { /** * Creates a rpc entry value. + * * @param value the value * @param time the creation time to use (instead of the current time) * @return The entry value @@ -328,6 +358,7 @@ public final class NetworkTableValue { /** * Creates a boolean array entry value. + * * @param value the value * @return The entry value */ @@ -337,6 +368,7 @@ public final class NetworkTableValue { /** * Creates a boolean array entry value. + * * @param value the value * @param time the creation time to use (instead of the current time) * @return The entry value @@ -347,6 +379,7 @@ public final class NetworkTableValue { /** * Creates a boolean array entry value. + * * @param value the value * @return The entry value */ @@ -356,6 +389,7 @@ public final class NetworkTableValue { /** * Creates a boolean array entry value. + * * @param value the value * @param time the creation time to use (instead of the current time) * @return The entry value @@ -366,6 +400,7 @@ public final class NetworkTableValue { /** * Creates a double array entry value. + * * @param value the value * @return The entry value */ @@ -375,6 +410,7 @@ public final class NetworkTableValue { /** * Creates a double array entry value. + * * @param value the value * @param time the creation time to use (instead of the current time) * @return The entry value @@ -385,6 +421,7 @@ public final class NetworkTableValue { /** * Creates a double array entry value. + * * @param value the value * @return The entry value */ @@ -394,6 +431,7 @@ public final class NetworkTableValue { /** * Creates a double array entry value. + * * @param value the value * @param time the creation time to use (instead of the current time) * @return The entry value @@ -404,6 +442,7 @@ public final class NetworkTableValue { /** * Creates a string array entry value. + * * @param value the value * @return The entry value */ @@ -413,6 +452,7 @@ public final class NetworkTableValue { /** * Creates a string array entry value. + * * @param value the value * @param time the creation time to use (instead of the current time) * @return The entry value diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/RpcAnswer.java b/ntcore/src/main/java/edu/wpi/first/networktables/RpcAnswer.java index 293814fa3e..a0de762f85 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/RpcAnswer.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/RpcAnswer.java @@ -33,6 +33,7 @@ public final class RpcAnswer { /** Constructor. * This should generally only be used internally to NetworkTables. + * * @param inst Instance * @param entry Entry handle * @param call Call handle @@ -65,6 +66,7 @@ public final class RpcAnswer { /** * Determines if the native handle is valid. + * * @return True if the native handle is valid, false otherwise. */ public boolean isValid() { @@ -73,6 +75,7 @@ public final class RpcAnswer { /** * Post RPC response (return value) for a polled RPC. + * * @param result result raw data that will be provided to remote caller * @return true if the response was posted, otherwise false */ @@ -90,6 +93,7 @@ public final class RpcAnswer { /** * Get the entry as an object. + * * @return NetworkTableEntry for the RPC. */ NetworkTableEntry getEntry() { diff --git a/ntcore/src/main/java/edu/wpi/first/networktables/RpcCall.java b/ntcore/src/main/java/edu/wpi/first/networktables/RpcCall.java index a473957608..1b377f632b 100644 --- a/ntcore/src/main/java/edu/wpi/first/networktables/RpcCall.java +++ b/ntcore/src/main/java/edu/wpi/first/networktables/RpcCall.java @@ -13,6 +13,7 @@ package edu.wpi.first.networktables; public final class RpcCall implements AutoCloseable { /** Constructor. * This should generally only be used internally to NetworkTables. + * * @param entry Entry * @param call Call handle */ @@ -38,6 +39,7 @@ public final class RpcCall implements AutoCloseable { /** * Determines if the native handle is valid. + * * @return True if the native handle is valid, false otherwise. */ public boolean isValid() { @@ -46,6 +48,7 @@ public final class RpcCall implements AutoCloseable { /** * Get the RPC entry. + * * @return NetworkTableEntry for the RPC. */ public NetworkTableEntry getEntry() { @@ -54,6 +57,7 @@ public final class RpcCall implements AutoCloseable { /** * Get the call native handle. + * * @return Native handle. */ public int getCall() { @@ -63,6 +67,7 @@ public final class RpcCall implements AutoCloseable { /** * Get the result (return value). This function blocks until * the result is received. + * * @return Received result (output) */ public byte[] getResult() { @@ -76,6 +81,7 @@ public final class RpcCall implements AutoCloseable { /** * Get the result (return value). This function blocks until * the result is received or it times out. + * * @param timeout timeout, in seconds * @return Received result (output) */ diff --git a/ntcore/src/main/native/include/networktables/EntryListenerFlags.h b/ntcore/src/main/native/include/networktables/EntryListenerFlags.h index b43f133ec1..c5cc6202ce 100644 --- a/ntcore/src/main/native/include/networktables/EntryListenerFlags.h +++ b/ntcore/src/main/native/include/networktables/EntryListenerFlags.h @@ -12,6 +12,7 @@ namespace nt { +/** Entry listener flags */ namespace EntryListenerFlags { /** @@ -26,15 +27,19 @@ namespace EntryListenerFlags { * By default, notifications are only generated for remote changes occurring * after the listener is created. The constants kImmediate and kLocal are * modifiers that cause notifications to be generated at other times. + * + * @ingroup ntcore_cpp_api */ enum { - /** Initial listener addition. + /** + * Initial listener addition. * Set this flag to receive immediate notification of entries matching the * flag criteria (generally only useful when combined with kNew). */ kImmediate = NT_NOTIFY_IMMEDIATE, - /** Changed locally. + /** + * Changed locally. * Set this flag to receive notification of both local changes and changes * coming from remote nodes. By default, notifications are only generated * for remote changes. Must be combined with some combination of kNew, @@ -43,23 +48,27 @@ enum { */ kLocal = NT_NOTIFY_LOCAL, - /** Newly created entry. + /** + * Newly created entry. * Set this flag to receive a notification when an entry is created. */ kNew = NT_NOTIFY_NEW, - /** Entry was deleted. + /** + * Entry was deleted. * Set this flag to receive a notification when an entry is deleted. */ kDelete = NT_NOTIFY_DELETE, - /** Entry's value changed. + /** + * Entry's value changed. * Set this flag to receive a notification when an entry's value (or type) * changes. */ kUpdate = NT_NOTIFY_UPDATE, - /** Entry's flags changed. + /** + * Entry's flags changed. * Set this flag to receive a notification when an entry's flags value * changes. */ diff --git a/ntcore/src/main/native/include/networktables/NetworkTable.h b/ntcore/src/main/native/include/networktables/NetworkTable.h index 0b609b4049..8e664e770c 100644 --- a/ntcore/src/main/native/include/networktables/NetworkTable.h +++ b/ntcore/src/main/native/include/networktables/NetworkTable.h @@ -38,8 +38,15 @@ class NetworkTableInstance; #pragma GCC diagnostic ignored "-Wdeprecated-declarations" #endif +/** + * @defgroup ntcore_cpp_api ntcore C++ object-oriented API + * + * Recommended interface for C++, identical to Java API. + */ + /** * A network table that knows its subtable path. + * @ingroup ntcore_cpp_api */ class NetworkTable final : public ITable { private: @@ -64,6 +71,7 @@ class NetworkTable final : public ITable { /** * Gets the "base name" of a key. For example, "/foo/bar" becomes "bar". * If the key has a trailing slash, returns an empty string. + * * @param key key * @return base name */ @@ -96,6 +104,7 @@ class NetworkTable final : public ITable { * Gets a list of the names of all the super tables of a given key. For * example, the key "/foo/bar/baz" has a hierarchy of "/", "/foo", * "/foo/bar", and "/foo/bar/baz". + * * @param key the key * @return List of super tables */ @@ -110,6 +119,7 @@ class NetworkTable final : public ITable { /** * Gets the instance for the table. + * * @return Instance */ NetworkTableInstance GetInstance() const; @@ -153,6 +163,7 @@ class NetworkTable final : public ITable { * set the team the robot is configured for (this will set the mdns address * that network tables will connect to in client mode) * This must be called before initialize or GetTable + * * @param team the team number */ WPI_DEPRECATED( @@ -181,6 +192,7 @@ class NetworkTable final : public ITable { /** * Set the port number that network tables will connect to in client * mode or listen to in server mode. + * * @param port the port number */ WPI_DEPRECATED( @@ -192,6 +204,7 @@ class NetworkTable final : public ITable { /** * Enable requesting the server address from the Driver Station. + * * @param enabled whether to enable the connection to the local DS */ WPI_DEPRECATED( @@ -201,6 +214,7 @@ class NetworkTable final : public ITable { /** * Sets the persistent filename. + * * @param filename the filename that the network tables server uses for * automatic loading and saving of persistent values */ @@ -212,6 +226,7 @@ class NetworkTable final : public ITable { /** * Sets the network identity. * This is provided in the connection info on the remote end. + * * @param name identity */ WPI_DEPRECATED("use NetworkTableInstance::SetNetworkIdentity() instead") @@ -278,6 +293,7 @@ class NetworkTable final : public ITable { /** * Gets the entry for a subkey. + * * @param key the key name * @return Network table entry. */ @@ -285,6 +301,7 @@ class NetworkTable final : public ITable { /** * Listen to keys only within this table. + * * @param listener listener to add * @param flags EntryListenerFlags bitmask * @return Listener handle @@ -294,6 +311,7 @@ class NetworkTable final : public ITable { /** * Listen to a single key. + * * @param key the key name * @param listener listener to add * @param flags EntryListenerFlags bitmask @@ -305,6 +323,7 @@ class NetworkTable final : public ITable { /** * Remove an entry listener. + * * @param listener listener handle */ void RemoveEntryListener(NT_EntryListener listener) const; @@ -313,6 +332,7 @@ class NetworkTable final : public ITable { * Listen for sub-table creation. * This calls the listener once for each newly created sub-table. * It immediately calls the listener for any existing sub-tables. + * * @param listener listener to add * @param localNotify notify local changes as well as remote * @return Listener handle @@ -322,6 +342,7 @@ class NetworkTable final : public ITable { /** * Remove a sub-table listener. + * * @param listener listener handle */ void RemoveTableListener(NT_EntryListener listener) const; @@ -387,6 +408,7 @@ class NetworkTable final : public ITable { /** * Gets all keys in the table (not including sub-tables). + * * @param types bitmask of types; 0 is treated as a "don't care". * @return keys currently in the table */ @@ -394,6 +416,7 @@ class NetworkTable final : public ITable { /** * Gets the names of all subtables in the table. + * * @return subtables currently in the table */ std::vector GetSubTables() const override; @@ -465,6 +488,7 @@ class NetworkTable final : public ITable { /** * Gets the current value in the table, setting it if it does not exist. + * * @param key the key * @param defaultValue the default value to set if key doesn't exist. * @returns False if the table key exists with a different type @@ -492,6 +516,7 @@ class NetworkTable final : public ITable { /** * Gets the current value in the table, setting it if it does not exist. + * * @param key the key * @param defaultValue the default value to set if key doesn't exist. * @returns False if the table key exists with a different type @@ -520,6 +545,7 @@ class NetworkTable final : public ITable { /** * Gets the current value in the table, setting it if it does not exist. + * * @param key the key * @param defaultValue the default value to set if key doesn't exist. * @returns False if the table key exists with a different type @@ -539,6 +565,7 @@ class NetworkTable final : public ITable { /** * Put a boolean array in the table + * * @param key the key to be assigned to * @param value the value that will be assigned * @return False if the table key already exists with a different type @@ -551,9 +578,10 @@ class NetworkTable final : public ITable { /** * Gets the current value in the table, setting it if it does not exist. + * * @param key the key * @param defaultValue the default value to set if key doesn't exist. - * @returns False if the table key exists with a different type + * @return False if the table key exists with a different type */ bool SetDefaultBooleanArray(StringRef key, ArrayRef defaultValue) override; @@ -561,6 +589,7 @@ class NetworkTable final : public ITable { /** * Returns the boolean array the key maps to. If the key does not exist or is * of different type, it will return the default value. + * * @param key the key to look up * @param defaultValue the value to be returned if no value is found * @return the value associated with the given key or the given default value @@ -578,6 +607,7 @@ class NetworkTable final : public ITable { /** * Put a number array in the table + * * @param key the key to be assigned to * @param value the value that will be assigned * @return False if the table key already exists with a different type @@ -586,6 +616,7 @@ class NetworkTable final : public ITable { /** * Gets the current value in the table, setting it if it does not exist. + * * @param key the key * @param defaultValue the default value to set if key doesn't exist. * @returns False if the table key exists with a different type @@ -596,6 +627,7 @@ class NetworkTable final : public ITable { /** * Returns the number array the key maps to. If the key does not exist or is * of different type, it will return the default value. + * * @param key the key to look up * @param defaultValue the value to be returned if no value is found * @return the value associated with the given key or the given default value @@ -609,6 +641,7 @@ class NetworkTable final : public ITable { /** * Put a string array in the table + * * @param key the key to be assigned to * @param value the value that will be assigned * @return False if the table key already exists with a different type @@ -617,6 +650,7 @@ class NetworkTable final : public ITable { /** * Gets the current value in the table, setting it if it does not exist. + * * @param key the key * @param defaultValue the default value to set if key doesn't exist. * @returns False if the table key exists with a different type @@ -627,6 +661,7 @@ class NetworkTable final : public ITable { /** * Returns the string array the key maps to. If the key does not exist or is * of different type, it will return the default value. + * * @param key the key to look up * @param defaultValue the value to be returned if no value is found * @return the value associated with the given key or the given default value @@ -640,6 +675,7 @@ class NetworkTable final : public ITable { /** * Put a raw value (byte array) in the table + * * @param key the key to be assigned to * @param value the value that will be assigned * @return False if the table key already exists with a different type @@ -648,15 +684,17 @@ class NetworkTable final : public ITable { /** * Gets the current value in the table, setting it if it does not exist. + * * @param key the key * @param defaultValue the default value to set if key doesn't exist. - * @returns False if the table key exists with a different type + * @return False if the table key exists with a different type */ bool SetDefaultRaw(StringRef key, StringRef defaultValue) override; /** * Returns the raw value (byte array) the key maps to. If the key does not * exist or is of different type, it will return the default value. + * * @param key the key to look up * @param defaultValue the value to be returned if no value is found * @return the value associated with the given key or the given default value @@ -678,9 +716,10 @@ class NetworkTable final : public ITable { /** * Gets the current value in the table, setting it if it does not exist. + * * @param key the key * @param defaultValue the default value to set if key doesn't exist. - * @returns False if the table key exists with a different type + * @return False if the table key exists with a different type */ bool SetDefaultValue(const Twine& key, std::shared_ptr defaultValue) override; @@ -696,6 +735,7 @@ class NetworkTable final : public ITable { /** * Gets the full path of this table. Does not include the trailing "/". + * * @return The path (e.g "", "/foo"). */ StringRef GetPath() const override; @@ -703,6 +743,7 @@ class NetworkTable final : public ITable { /** * Save table values to a file. The file format used is identical to * that used for SavePersistent. + * * @param filename filename * @return error string, or nullptr if successful */ @@ -711,6 +752,7 @@ class NetworkTable final : public ITable { /** * Load table values from a file. The file format used is identical to * that used for SavePersistent / LoadPersistent. + * * @param filename filename * @param warn callback function for warnings * @return error string, or nullptr if successful diff --git a/ntcore/src/main/native/include/networktables/NetworkTableEntry.h b/ntcore/src/main/native/include/networktables/NetworkTableEntry.h index 4e2684ec5a..16b5c61d9c 100644 --- a/ntcore/src/main/native/include/networktables/NetworkTableEntry.h +++ b/ntcore/src/main/native/include/networktables/NetworkTableEntry.h @@ -31,11 +31,14 @@ using wpi::Twine; class NetworkTableInstance; -/** NetworkTables Entry */ +/** + * NetworkTables Entry + * @ingroup ntcore_cpp_api + */ class NetworkTableEntry final { public: /** - * Flag values (as returned by {@link #getFlags()}). + * Flag values (as returned by GetFlags()). */ enum Flags { kPersistent = NT_PERSISTENT }; @@ -46,60 +49,70 @@ class NetworkTableEntry final { /** * Construct from native handle. + * * @param handle Native handle */ explicit NetworkTableEntry(NT_Entry handle); /** * Determines if the native handle is valid. + * * @return True if the native handle is valid, false otherwise. */ explicit operator bool() const { return m_handle != 0; } /** * Gets the native handle for the entry. + * * @return Native handle */ NT_Entry GetHandle() const; /** * Gets the instance for the entry. + * * @return Instance */ NetworkTableInstance GetInstance() const; /** * Determines if the entry currently exists. + * * @return True if the entry exists, false otherwise. */ bool Exists() const; /** * Gets the name of the entry (the key). + * * @return the entry's name */ std::string GetName() const; /** * Gets the type of the entry. + * * @return the entry's type */ NetworkTableType GetType() const; /** * Returns the flags. + * * @return the flags (bitmask) */ unsigned int GetFlags() const; /** * Gets the last time the entry's value was changed. + * * @return Entry last change time */ uint64_t GetLastChange() const; /** * Gets combined information about the entry. + * * @return Entry information */ EntryInfo GetInfo() const; @@ -150,6 +163,7 @@ class NetworkTableEntry final { /** * Gets the entry's value as a boolean array. If the entry does not exist * or is of different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value * @@ -165,6 +179,7 @@ class NetworkTableEntry final { /** * Gets the entry's value as a double array. If the entry does not exist * or is of different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value * @@ -176,6 +191,7 @@ class NetworkTableEntry final { /** * Gets the entry's value as a string array. If the entry does not exist * or is of different type, it will return the default value. + * * @param defaultValue the value to be returned if no value is found * @return the entry's value or the given default value * @@ -187,6 +203,7 @@ class NetworkTableEntry final { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -194,6 +211,7 @@ class NetworkTableEntry final { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -201,6 +219,7 @@ class NetworkTableEntry final { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -208,6 +227,7 @@ class NetworkTableEntry final { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -215,6 +235,7 @@ class NetworkTableEntry final { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -222,6 +243,7 @@ class NetworkTableEntry final { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -229,6 +251,7 @@ class NetworkTableEntry final { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -236,6 +259,7 @@ class NetworkTableEntry final { /** * Sets the entry's value if it does not exist. + * * @param defaultValue the default value to set * @return False if the entry exists with a different type */ @@ -243,6 +267,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -250,6 +275,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -257,6 +283,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -264,6 +291,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -271,6 +299,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -278,6 +307,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -285,6 +315,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -292,6 +323,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. + * * @param value the value to set * @return False if the entry exists with a different type */ @@ -300,6 +332,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ void ForceSetValue(std::shared_ptr value); @@ -307,6 +340,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ void ForceSetBoolean(bool value); @@ -314,6 +348,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ void ForceSetDouble(double value); @@ -321,6 +356,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ void ForceSetString(const Twine& value); @@ -328,6 +364,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ void ForceSetRaw(StringRef value); @@ -335,6 +372,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ void ForceSetBooleanArray(ArrayRef value); @@ -342,6 +380,7 @@ class NetworkTableEntry final { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ void ForceSetDoubleArray(ArrayRef value); @@ -349,18 +388,21 @@ class NetworkTableEntry final { /** * Sets the entry's value. If the value is of different type, the type is * changed to match the new value. + * * @param value the value to set */ void ForceSetStringArray(ArrayRef value); /** * Sets flags. + * * @param flags the flags to set (bitmask) */ void SetFlags(unsigned int flags); /** * Clears flags. + * * @param flags the flags to clear (bitmask) */ void ClearFlags(unsigned int flags); @@ -377,6 +419,7 @@ class NetworkTableEntry final { /** * Returns whether the value is persistent through program restarts. + * * @return True if the value is persistent. */ bool IsPersistent() const; @@ -390,6 +433,7 @@ class NetworkTableEntry final { * Create a callback-based RPC entry point. Only valid to use on the server. * The callback function will be called when the RPC is called. * This function creates RPC version 0 definitions (raw data in and out). + * * @param callback callback function */ void CreateRpc(std::function callback); @@ -407,6 +451,7 @@ class NetworkTableEntry final { * This function is non-blocking. Either RpcCall::GetResult() or * RpcCall::CancelResult() must be called on the return value to either * get or ignore the result of the call. + * * @param params parameter * @return RPC call object. */ @@ -425,6 +470,7 @@ class NetworkTableEntry final { /** * Remove an entry listener. + * * @param entry_listener Listener handle to remove */ void RemoveListener(NT_EntryListener entry_listener); diff --git a/ntcore/src/main/native/include/networktables/NetworkTableInstance.h b/ntcore/src/main/native/include/networktables/NetworkTableInstance.h index 0b79e180f4..ee0874545c 100644 --- a/ntcore/src/main/native/include/networktables/NetworkTableInstance.h +++ b/ntcore/src/main/native/include/networktables/NetworkTableInstance.h @@ -29,7 +29,8 @@ using wpi::ArrayRef; using wpi::StringRef; using wpi::Twine; -/** NetworkTables Instance. +/** + * NetworkTables Instance. * * Instances are completely independent from each other. Table operations on * one instance will not be visible to other instances unless the instances are @@ -46,6 +47,8 @@ using wpi::Twine; * Additional instances can be created with the Create() function. * Instances are not reference counted or RAII. Instead, they must be * explicitly destroyed (with Destroy()). + * + * @ingroup ntcore_cpp_api */ class NetworkTableInstance final { public: @@ -88,42 +91,49 @@ class NetworkTableInstance final { /** * Construct from native handle. + * * @param handle Native handle */ explicit NetworkTableInstance(NT_Inst inst) noexcept; /** * Determines if the native handle is valid. + * * @return True if the native handle is valid, false otherwise. */ explicit operator bool() const { return m_handle != 0; } /** * Get global default instance. + * * @return Global default instance */ static NetworkTableInstance GetDefault(); /** * Create an instance. + * * @return Newly created instance */ static NetworkTableInstance Create(); /** * Destroys an instance (note: this has global effect). + * * @param inst Instance */ static void Destroy(NetworkTableInstance inst); /** * Gets the native handle for the entry. + * * @return Native handle */ NT_Inst GetHandle() const; /** * Gets the entry for a key. + * * @param name Key * @return Network table entry. */ @@ -131,6 +141,7 @@ class NetworkTableInstance final { /** * Get entries starting with the given prefix. + * * The results are optionally filtered by string prefix and entry type to * only return a subset of all entries. * @@ -144,6 +155,7 @@ class NetworkTableInstance final { /** * Get information about entries starting with the given prefix. + * * The results are optionally filtered by string prefix and entry type to * only return a subset of all entries. * @@ -170,8 +182,8 @@ class NetworkTableInstance final { void DeleteAllEntries(); /** - * @defgroup EntryListenerFunctions Entry Listener Functions * @{ + * @name Entry Listener Functions */ /** @@ -189,6 +201,7 @@ class NetworkTableInstance final { /** * Remove an entry listener. + * * @param entry_listener Listener handle to remove */ static void RemoveEntryListener(NT_EntryListener entry_listener); @@ -198,6 +211,7 @@ class NetworkTableInstance final { * for deterministic testing. This blocks until either the entry listener * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely * @return False if timed out, otherwise true. @@ -207,8 +221,8 @@ class NetworkTableInstance final { /** @} */ /** - * @defgroup ConnectionListenerFunctions Connection Listener Functions * @{ + * @name Connection Listener Functions */ /** @@ -224,17 +238,17 @@ class NetworkTableInstance final { /** * Remove a connection listener. + * * @param conn_listener Listener handle to remove */ static void RemoveConnectionListener(NT_ConnectionListener conn_listener); /** * Wait for the connection listener queue to be empty. This is primarily - * useful - * for deterministic testing. This blocks until either the connection - * listener - * queue is empty (e.g. there are no more events that need to be passed along - * to callbacks or poll queues) or the timeout expires. + * useful for deterministic testing. This blocks until either the connection + * listener queue is empty (e.g. there are no more events that need to be + * passed along to callbacks or poll queues) or the timeout expires. + * * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely * @return False if timed out, otherwise true. @@ -244,8 +258,8 @@ class NetworkTableInstance final { /** @} */ /** - * @defgroup RpcFunctions Remote Procedure Call Functions * @{ + * @name Remote Procedure Call Functions */ /** @@ -253,6 +267,7 @@ class NetworkTableInstance final { * for deterministic testing. This blocks until either the RPC call * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely * @return False if timed out, otherwise true. @@ -262,20 +277,23 @@ class NetworkTableInstance final { /** @} */ /** - * @defgroup NetworkFunctions Client/Server Functions * @{ + * @name Client/Server Functions */ /** * Set the network identity of this node. + * * This is the name used during the initial connection handshake, and is * visible through ConnectionInfo on the remote node. + * * @param name identity to advertise */ void SetNetworkIdentity(const Twine& name); /** * Get the current network mode. + * * @return Bitmask of NetworkMode. */ unsigned int GetNetworkMode() const; @@ -410,12 +428,14 @@ class NetworkTableInstance final { /** * Get information on the currently established network connections. * If operating as a client, this will return either zero or one values. + * * @return array of connection information */ std::vector GetConnections() const; /** * Return whether or not the instance is connected to another node. + * * @return True if connected. */ bool IsConnected() const; @@ -423,14 +443,15 @@ class NetworkTableInstance final { /** @} */ /** - * @defgroup FileFunctions File Save/Load Functions * @{ + * @name File Save/Load Functions */ /** * Save persistent values to a file. The server automatically does this, * but this function provides a way to save persistent values in the same * format to a file on either a client or a server. + * * @param filename filename * @return error string, or nullptr if successful */ @@ -440,6 +461,7 @@ class NetworkTableInstance final { * Load persistent values from a file. The server automatically does this * at startup, but this function provides a way to restore persistent values * in the same format from a file at any time on either a client or a server. + * * @param filename filename * @param warn callback function for warnings * @return error string, or nullptr if successful @@ -451,6 +473,7 @@ class NetworkTableInstance final { /** * Save table values to a file. The file format used is identical to * that used for SavePersistent. + * * @param filename filename * @param prefix save only keys starting with this prefix * @return error string, or nullptr if successful @@ -460,6 +483,7 @@ class NetworkTableInstance final { /** * Load table values from a file. The file format used is identical to * that used for SavePersistent / LoadPersistent. + * * @param filename filename * @param prefix load only keys starting with this prefix * @param warn callback function for warnings @@ -472,8 +496,8 @@ class NetworkTableInstance final { /** @} */ /** - * @defgroup LoggerFunctions Logger Functions * @{ + * @name Logger Functions */ /** @@ -493,16 +517,17 @@ class NetworkTableInstance final { /** * Remove a logger. + * * @param logger Logger handle to remove */ static void RemoveLogger(NT_Logger logger); /** * Wait for the incoming log event queue to be empty. This is primarily - * useful - * for deterministic testing. This blocks until either the log event + * useful for deterministic testing. This blocks until either the log event * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely * @return False if timed out, otherwise true. diff --git a/ntcore/src/main/native/include/networktables/NetworkTableType.h b/ntcore/src/main/native/include/networktables/NetworkTableType.h index 0d7cb06823..7ac3d9a3aa 100644 --- a/ntcore/src/main/native/include/networktables/NetworkTableType.h +++ b/ntcore/src/main/native/include/networktables/NetworkTableType.h @@ -12,6 +12,10 @@ namespace nt { +/** + * NetworkTable entry type. + * @ingroup ntcore_cpp_api + */ enum class NetworkTableType { kUnassigned = NT_UNASSIGNED, kBoolean = NT_BOOLEAN, diff --git a/ntcore/src/main/native/include/networktables/NetworkTableValue.h b/ntcore/src/main/native/include/networktables/NetworkTableValue.h index 1523791fd8..ae178c81e6 100644 --- a/ntcore/src/main/native/include/networktables/NetworkTableValue.h +++ b/ntcore/src/main/native/include/networktables/NetworkTableValue.h @@ -31,6 +31,7 @@ using wpi::Twine; /** * A network table entry value. + * @ingroup ntcore_cpp_api */ class Value final { struct private_init {}; @@ -42,83 +43,96 @@ class Value final { /** * Get the data type. + * * @return The type. */ NT_Type type() const { return m_val.type; } /** * Get the data value stored. + * * @return The type. */ const NT_Value& value() const { return m_val; } /** * Get the creation time of the value. + * * @return The time, in the units returned by nt::Now(). */ uint64_t last_change() const { return m_val.last_change; } /** * Get the creation time of the value. + * * @return The time, in the units returned by nt::Now(). */ uint64_t time() const { return m_val.last_change; } /** - * @defgroup TypeCheckers Type Checkers * @{ + * @name Type Checkers */ /** * Determine if entry value contains a value or is unassigned. + * * @return True if the entry value contains a value. */ bool IsValid() const { return m_val.type != NT_UNASSIGNED; } /** * Determine if entry value contains a boolean. + * * @return True if the entry value is of boolean type. */ bool IsBoolean() const { return m_val.type == NT_BOOLEAN; } /** * Determine if entry value contains a double. + * * @return True if the entry value is of double type. */ bool IsDouble() const { return m_val.type == NT_DOUBLE; } /** * Determine if entry value contains a string. + * * @return True if the entry value is of string type. */ bool IsString() const { return m_val.type == NT_STRING; } /** * Determine if entry value contains a raw. + * * @return True if the entry value is of raw type. */ bool IsRaw() const { return m_val.type == NT_RAW; } /** * Determine if entry value contains a rpc definition. + * * @return True if the entry value is of rpc definition type. */ bool IsRpc() const { return m_val.type == NT_RPC; } /** * Determine if entry value contains a boolean array. + * * @return True if the entry value is of boolean array type. */ bool IsBooleanArray() const { return m_val.type == NT_BOOLEAN_ARRAY; } /** * Determine if entry value contains a double array. + * * @return True if the entry value is of double array type. */ bool IsDoubleArray() const { return m_val.type == NT_DOUBLE_ARRAY; } /** * Determine if entry value contains a string array. + * * @return True if the entry value is of string array type. */ bool IsStringArray() const { return m_val.type == NT_STRING_ARRAY; } @@ -126,12 +140,13 @@ class Value final { /** @} */ /** - * @defgroup TypeSafeGetters Type-Safe Getters * @{ + * @name Type-Safe Getters */ /** * Get the entry's boolean value. + * * @return The boolean value. */ bool GetBoolean() const { @@ -141,6 +156,7 @@ class Value final { /** * Get the entry's double value. + * * @return The double value. */ double GetDouble() const { @@ -150,6 +166,7 @@ class Value final { /** * Get the entry's string value. + * * @return The string value. */ StringRef GetString() const { @@ -159,6 +176,7 @@ class Value final { /** * Get the entry's raw value. + * * @return The raw value. */ StringRef GetRaw() const { @@ -168,6 +186,7 @@ class Value final { /** * Get the entry's rpc definition value. + * * @return The rpc definition value. */ StringRef GetRpc() const { @@ -177,6 +196,7 @@ class Value final { /** * Get the entry's boolean array value. + * * @return The boolean array value. */ ArrayRef GetBooleanArray() const { @@ -187,6 +207,7 @@ class Value final { /** * Get the entry's double array value. + * * @return The double array value. */ ArrayRef GetDoubleArray() const { @@ -197,6 +218,7 @@ class Value final { /** * Get the entry's string array value. + * * @return The string array value. */ ArrayRef GetStringArray() const { @@ -207,12 +229,13 @@ class Value final { /** @} */ /** - * @defgroup Factories Factory functions * @{ + * @name Factory functions */ /** * Creates a boolean entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -226,6 +249,7 @@ class Value final { /** * Creates a double entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -239,6 +263,7 @@ class Value final { /** * Creates a string entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -255,6 +280,7 @@ class Value final { /** * Creates a string entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -277,6 +303,7 @@ class Value final { /** * Creates a raw entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -292,6 +319,7 @@ class Value final { /** * Creates a raw entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -314,6 +342,7 @@ class Value final { /** * Creates a rpc entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -329,6 +358,7 @@ class Value final { /** * Creates a rpc entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -345,6 +375,7 @@ class Value final { /** * Creates a boolean array entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -355,6 +386,7 @@ class Value final { /** * Creates a double array entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -365,6 +397,7 @@ class Value final { /** * Creates a string array entry value. + * * @param value the value * @param time if nonzero, the creation time to use (instead of the current * time) @@ -373,7 +406,16 @@ class Value final { static std::shared_ptr MakeStringArray(ArrayRef value, uint64_t time = 0); - // Note: This function moves the values out of the vector. + /** + * Creates a string array entry value. + * + * @param value the value + * @param time if nonzero, the creation time to use (instead of the current + * time) + * @return The entry value + * + * @note This function moves the values out of the vector. + */ static std::shared_ptr MakeStringArray( std::vector&& value, uint64_t time = 0); @@ -394,7 +436,10 @@ inline bool operator!=(const Value& lhs, const Value& rhs) { return !(lhs == rhs); } -/** NetworkTable Value alias for similarity with Java. */ +/** + * NetworkTable Value alias for similarity with Java. + * @ingroup ntcore_cpp_api + */ typedef Value NetworkTableValue; } // namespace nt diff --git a/ntcore/src/main/native/include/networktables/RpcCall.h b/ntcore/src/main/native/include/networktables/RpcCall.h index 6872d9f049..7d83140496 100644 --- a/ntcore/src/main/native/include/networktables/RpcCall.h +++ b/ntcore/src/main/native/include/networktables/RpcCall.h @@ -17,7 +17,10 @@ namespace nt { class NetworkTableEntry; -/** NetworkTables Remote Procedure Call */ +/** + * NetworkTables Remote Procedure Call + * @ingroup ntcore_cpp_api + */ class RpcCall final { public: /** @@ -27,6 +30,7 @@ class RpcCall final { /** * Construct from native handles. + * * @param entry Entry handle * @param call Call handle */ @@ -43,18 +47,21 @@ class RpcCall final { /** * Determines if the native handle is valid. + * * @return True if the native handle is valid, false otherwise. */ explicit operator bool() const { return m_call != 0; } /** * Get the RPC entry. + * * @return NetworkTableEntry for the RPC. */ NetworkTableEntry GetEntry() const; /** * Get the call native handle. + * * @return Native handle. */ NT_RpcCall GetCall() const { return m_call; } @@ -62,6 +69,7 @@ class RpcCall final { /** * Get the result (return value). This function blocks until * the result is received. + * * @param result received result (output) * @return False on error, true otherwise. */ @@ -70,6 +78,7 @@ class RpcCall final { /** * Get the result (return value). This function blocks until * the result is received or it times out. + * * @param result received result (output) * @param timeout timeout, in seconds * @param timed_out true if the timeout period elapsed (output) diff --git a/ntcore/src/main/native/include/networktables/TableEntryListener.h b/ntcore/src/main/native/include/networktables/TableEntryListener.h index dca144c359..c4552678c7 100644 --- a/ntcore/src/main/native/include/networktables/TableEntryListener.h +++ b/ntcore/src/main/native/include/networktables/TableEntryListener.h @@ -32,6 +32,8 @@ using wpi::StringRef; * @param value the new value * @param flags update flags; for example, EntryListenerFlags.kNew if the key * did not previously exist + * + * @ingroup ntcore_cpp_api */ typedef std::function diff --git a/ntcore/src/main/native/include/ntcore_c.h b/ntcore/src/main/native/include/ntcore_c.h index 943efb8892..60773ea777 100644 --- a/ntcore/src/main/native/include/ntcore_c.h +++ b/ntcore/src/main/native/include/ntcore_c.h @@ -22,6 +22,14 @@ extern "C" { #endif +/** + * @defgroup ntcore_c_api ntcore C API + * + * Handle-based interface for C. + * + * @{ + */ + /** Typedefs */ typedef int NT_Bool; @@ -262,19 +270,21 @@ struct NT_LogMessage { }; /** - * @defgroup InstanceFunctions Instance Functions + * @defgroup ntcore_instance_cfunc Instance Functions * @{ */ /** * Get default instance. * This is the instance used by non-handle-taking functions. + * * @return Instance handle */ NT_Inst NT_GetDefaultInstance(void); /** * Create an instance. + * * @return Instance handle */ NT_Inst NT_CreateInstance(void); @@ -282,12 +292,14 @@ NT_Inst NT_CreateInstance(void); /** * Destroy an instance. * The default instance cannot be destroyed. + * * @param inst Instance handle */ void NT_DestroyInstance(NT_Inst inst); /** * Get instance handle from another handle. + * * @param handle handle * @return Instance handle */ @@ -296,12 +308,13 @@ NT_Inst NT_GetInstanceFromHandle(NT_Handle handle); /** @} */ /** - * @defgroup TableFunctions Table Functions + * @defgroup ntcore_table_cfunc Table Functions * @{ */ /** * Get Entry Handle. + * * @param inst instance handle * @param name entry name (UTF-8 string) * @param name_len length of name in bytes @@ -311,6 +324,7 @@ NT_Entry NT_GetEntry(NT_Inst inst, const char* name, size_t name_len); /** * Get Entry Handles. + * * Returns an array of entry handles. The results are optionally * filtered by string prefix and entry type to only return a subset of all * entries. @@ -328,6 +342,7 @@ NT_Entry* NT_GetEntries(NT_Inst inst, const char* prefix, size_t prefix_len, /** * Gets the name of the specified entry. * Returns an empty string if the handle is invalid. + * * @param entry entry handle * @param name_len length of the returned string (output parameter) * @return Entry name @@ -336,6 +351,7 @@ char* NT_GetEntryName(NT_Entry entry, size_t* name_len); /** * Gets the type for the specified key, or unassigned if non existent. + * * @param entry entry handle * @return Entry type */ @@ -344,6 +360,7 @@ enum NT_Type NT_GetEntryType(NT_Entry entry); /** * Gets the last time the entry was changed. * Returns 0 if the handle is invalid. + * * @param entry entry handle * @return Entry last change time */ @@ -351,6 +368,7 @@ uint64_t NT_GetEntryLastChange(NT_Entry entry); /** * Get Entry Value. + * * Returns copy of current entry value. * Note that one of the type options is "unassigned". * @@ -365,6 +383,7 @@ void NT_GetEntryValue(NT_Entry entry, struct NT_Value* value); /** * Set Default Entry Value. + * * Returns copy of current entry value if it exists. * Otherwise, sets passed in value, and returns set value. * Note that one of the type options is "unassigned". @@ -378,6 +397,7 @@ NT_Bool NT_SetDefaultEntryValue(NT_Entry entry, /** * Set Entry Value. + * * Sets new entry value. If type of new value differs from the type of the * currently stored entry, returns error and does not update value. * @@ -389,6 +409,7 @@ NT_Bool NT_SetEntryValue(NT_Entry entry, const struct NT_Value* value); /** * Set Entry Type and Value. + * * Sets new entry value. If type of new value differs from the type of the * currently stored entry, the currently stored entry type is overridden * (generally this will generate an Entry Assignment message). @@ -403,6 +424,7 @@ void NT_SetEntryTypeValue(NT_Entry entry, const struct NT_Value* value); /** * Set Entry Flags. + * * @param entry entry handle * @param flags flags value (bitmask of NT_EntryFlags) */ @@ -410,6 +432,7 @@ void NT_SetEntryFlags(NT_Entry entry, unsigned int flags); /** * Get Entry Flags. + * * @param entry entry handle * @return Flags value (bitmask of NT_EntryFlags) */ @@ -417,6 +440,7 @@ unsigned int NT_GetEntryFlags(NT_Entry entry); /** * Delete Entry. + * * Deletes an entry. This is a new feature in version 3.0 of the protocol, * so this may not have an effect if any other node in the network is not * version 3.0 or newer. @@ -431,6 +455,7 @@ void NT_DeleteEntry(NT_Entry entry); /** * Delete All Entries. + * * Deletes ALL table entries. This is a new feature in version 3.0 of the * so this may not have an effect if any other node in the network is not * version 3.0 or newer. @@ -445,6 +470,7 @@ void NT_DeleteAllEntries(NT_Inst inst); /** * Get Entry Information. + * * Returns an array of entry information (entry handle, name, entry type, * and timestamp of last change to type/value). The results are optionally * filtered by string prefix and entry type to only return a subset of all @@ -465,6 +491,7 @@ struct NT_EntryInfo* NT_GetEntryInfo(NT_Inst inst, const char* prefix, /** * Get Entry Information. + * * Returns information about an entry (name, entry type, * and timestamp of last change to type/value). * @@ -477,7 +504,7 @@ NT_Bool NT_GetEntryInfoHandle(NT_Entry entry, struct NT_EntryInfo* info); /** @} */ /** - * @defgroup EntryListenerFunctions Entry Listener Functions + * @defgroup ntcore_entrylistener_cfunc Entry Listener Functions * @{ */ @@ -522,10 +549,12 @@ NT_EntryListener NT_AddEntryListenerSingle(NT_Entry entry, void* data, /** * Create a entry listener poller. + * * A poller provides a single queue of poll events. Events linked to this * poller (using NT_AddPolledEntryListener()) will be stored in the queue and * must be collected by calling NT_PollEntryListener(). * The returned handle must be destroyed with NT_DestroyEntryListenerPoller(). + * * @param inst instance handle * @return poller handle */ @@ -534,6 +563,7 @@ NT_EntryListenerPoller NT_CreateEntryListenerPoller(NT_Inst inst); /** * Destroy a entry listener poller. This will abort any blocked polling * call and prevent additional events from being generated for this poller. + * * @param poller poller handle */ void NT_DestroyEntryListenerPoller(NT_EntryListenerPoller poller); @@ -541,6 +571,7 @@ void NT_DestroyEntryListenerPoller(NT_EntryListenerPoller poller); /** * Create a polled entry listener. * The caller is responsible for calling NT_PollEntryListener() to poll. + * * @param poller poller handle * @param prefix UTF-8 string prefix * @param flags NT_NotifyKind bitmask @@ -554,6 +585,7 @@ NT_EntryListener NT_AddPolledEntryListener(NT_EntryListenerPoller poller, /** * Create a polled entry listener. * The caller is responsible for calling NT_PollEntryListener() to poll. + * * @param poller poller handle * @param prefix UTF-8 string prefix * @param flags NT_NotifyKind bitmask @@ -565,9 +597,11 @@ NT_EntryListener NT_AddPolledEntryListenerSingle(NT_EntryListenerPoller poller, /** * Get the next entry listener event. This blocks until the next event occurs. + * * This is intended to be used with NT_AddPolledEntryListener(void); entry * listeners created using NT_AddEntryListener() will not be serviced through * this function. + * * @param poller poller handle * @param len length of returned array (output) * @return Array of information on the entry listener events. Returns NULL if @@ -581,6 +615,7 @@ struct NT_EntryNotification* NT_PollEntryListener(NT_EntryListenerPoller poller, * or it times out. This is intended to be used with * NT_AddPolledEntryListener(); entry listeners created using * NT_AddEntryListener() will not be serviced through this function. + * * @param poller poller handle * @param len length of returned array (output) * @param timeout timeout, in seconds @@ -597,12 +632,14 @@ struct NT_EntryNotification* NT_PollEntryListenerTimeout( * Cancel a PollEntryListener call. This wakes up a call to * PollEntryListener for this poller and causes it to immediately return * an empty array. + * * @param poller poller handle */ void NT_CancelPollEntryListener(NT_EntryListenerPoller poller); /** * Remove an entry listener. + * * @param entry_listener Listener handle to remove */ void NT_RemoveEntryListener(NT_EntryListener entry_listener); @@ -612,6 +649,7 @@ void NT_RemoveEntryListener(NT_EntryListener entry_listener); * for deterministic testing. This blocks until either the entry listener * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param inst instance handle * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely @@ -622,7 +660,7 @@ NT_Bool NT_WaitForEntryListenerQueue(NT_Inst inst, double timeout); /** @} */ /** - * @defgroup ConnectionListenerFunctions Connection Listener Functions + * @defgroup ntcore_connectionlistener_cfunc Connection Listener Functions * @{ */ @@ -656,6 +694,7 @@ NT_ConnectionListener NT_AddConnectionListener( * and must be collected by calling NT_PollConnectionListener(). * The returned handle must be destroyed with * NT_DestroyConnectionListenerPoller(). + * * @param inst instance handle * @return poller handle */ @@ -664,6 +703,7 @@ NT_ConnectionListenerPoller NT_CreateConnectionListenerPoller(NT_Inst inst); /** * Destroy a connection listener poller. This will abort any blocked polling * call and prevent additional events from being generated for this poller. + * * @param poller poller handle */ void NT_DestroyConnectionListenerPoller(NT_ConnectionListenerPoller poller); @@ -671,6 +711,7 @@ void NT_DestroyConnectionListenerPoller(NT_ConnectionListenerPoller poller); /** * Create a polled connection listener. * The caller is responsible for calling NT_PollConnectionListener() to poll. + * * @param poller poller handle * @param immediate_notify notify listener of all existing connections */ @@ -682,6 +723,7 @@ NT_ConnectionListener NT_AddPolledConnectionListener( * disconnect occurs. This is intended to be used with * NT_AddPolledConnectionListener(); connection listeners created using * NT_AddConnectionListener() will not be serviced through this function. + * * @param poller poller handle * @param len length of returned array (output) * @return Array of information on the connection events. Only returns NULL @@ -696,6 +738,7 @@ struct NT_ConnectionNotification* NT_PollConnectionListener( * disconnect occurs or it times out. This is intended to be used with * NT_AddPolledConnectionListener(); connection listeners created using * NT_AddConnectionListener() will not be serviced through this function. + * * @param poller poller handle * @param len length of returned array (output) * @param timeout timeout, in seconds @@ -712,12 +755,14 @@ struct NT_ConnectionNotification* NT_PollConnectionListenerTimeout( * Cancel a PollConnectionListener call. This wakes up a call to * PollConnectionListener for this poller and causes it to immediately return * an empty array. + * * @param poller poller handle */ void NT_CancelPollConnectionListener(NT_ConnectionListenerPoller poller); /** * Remove a connection listener. + * * @param conn_listener Listener handle to remove */ void NT_RemoveConnectionListener(NT_ConnectionListener conn_listener); @@ -727,6 +772,7 @@ void NT_RemoveConnectionListener(NT_ConnectionListener conn_listener); * for deterministic testing. This blocks until either the connection listener * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param inst instance handle * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely @@ -737,14 +783,16 @@ NT_Bool NT_WaitForConnectionListenerQueue(NT_Inst inst, double timeout); /** @} */ /** - * @defgroup RpcFunctions Remote Procedure Call Functions + * @defgroup ntcore_rpc_cfunc Remote Procedure Call Functions * @{ */ /** * Remote Procedure Call (RPC) callback function. + * * @param data data pointer provided to NT_CreateRpc() * @param call call information + * * Note: NT_PostRpcResponse() must be called by the callback to provide a * response to the call. */ @@ -753,6 +801,7 @@ typedef void (*NT_RpcCallback)(void* data, const struct NT_RpcAnswer* call); /** * Create a callback-based RPC entry point. Only valid to use on the server. * The callback function will be called when the RPC is called. + * * @param entry entry handle of RPC entry * @param def RPC definition * @param def_len length of def in bytes @@ -764,10 +813,12 @@ void NT_CreateRpc(NT_Entry entry, const char* def, size_t def_len, void* data, /** * Create a RPC call poller. Only valid to use on the server. + * * A poller provides a single queue of poll events. Events linked to this * poller (using NT_CreatePolledRpc()) will be stored in the queue and must be * collected by calling NT_PollRpc() or NT_PollRpcTimeout(). * The returned handle must be destroyed with NT_DestroyRpcCallPoller(). + * * @param inst instance handle * @return poller handle */ @@ -776,14 +827,17 @@ NT_RpcCallPoller NT_CreateRpcCallPoller(NT_Inst inst); /** * Destroy a RPC call poller. This will abort any blocked polling call and * prevent additional events from being generated for this poller. + * * @param poller poller handle */ void NT_DestroyRpcCallPoller(NT_RpcCallPoller poller); /** * Create a polled RPC entry point. Only valid to use on the server. + * * The caller is responsible for calling NT_PollRpc() or NT_PollRpcTimeout() * to poll for servicing incoming RPC calls. + * * @param entry entry handle of RPC entry * @param def RPC definition * @param def_len length of def in bytes @@ -799,6 +853,7 @@ void NT_CreatePolledRpc(NT_Entry entry, const char* def, size_t def_len, * function. Upon successful return, NT_PostRpcResponse() must be called to * send the return value to the caller. The returned array must be freed * using NT_DisposeRpcAnswerArray(). + * * @param poller poller handle * @param len length of returned array (output) * @return Array of RPC call information. Only returns NULL if an error @@ -813,6 +868,7 @@ struct NT_RpcAnswer* NT_PollRpc(NT_RpcCallPoller poller, size_t* len); * serviced through this function. Upon successful return, * NT_PostRpcResponse() must be called to send the return value to the caller. * The returned array must be freed using NT_DisposeRpcAnswerArray(). + * * @param poller poller handle * @param len length of returned array (output) * @param timeout timeout, in seconds @@ -827,6 +883,7 @@ struct NT_RpcAnswer* NT_PollRpcTimeout(NT_RpcCallPoller poller, size_t* len, /** * Cancel a PollRpc call. This wakes up a call to PollRpc for this poller * and causes it to immediately return an empty array. + * * @param poller poller handle */ void NT_CancelPollRpc(NT_RpcCallPoller poller); @@ -836,6 +893,7 @@ void NT_CancelPollRpc(NT_RpcCallPoller poller); * for deterministic testing. This blocks until either the RPC call * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param inst instance handle * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely @@ -845,8 +903,10 @@ NT_Bool NT_WaitForRpcCallQueue(NT_Inst inst, double timeout); /** * Post RPC response (return value) for a polled RPC. + * * The rpc and call parameters should come from the NT_RpcAnswer returned * by NT_PollRpc(). + * * @param entry entry handle of RPC entry (from NT_RpcAnswer) * @param call RPC call handle (from NT_RpcAnswer) * @param result result raw data that will be provided to remote caller @@ -858,9 +918,11 @@ NT_Bool NT_PostRpcResponse(NT_Entry entry, NT_RpcCall call, const char* result, /** * Call a RPC function. May be used on either the client or server. + * * This function is non-blocking. Either NT_GetRpcResult() or * NT_CancelRpcResult() must be called to either get or ignore the result of * the call. + * * @param entry entry handle of RPC entry * @param params parameter * @param params_len length of param in bytes @@ -872,6 +934,7 @@ NT_RpcCall NT_CallRpc(NT_Entry entry, const char* params, size_t params_len); /** * Get the result (return value) of a RPC call. This function blocks until * the result is received. + * * @param entry entry handle of RPC entry * @param call RPC call handle returned by NT_CallRpc() * @param result_len length of returned result in bytes @@ -882,6 +945,7 @@ char* NT_GetRpcResult(NT_Entry entry, NT_RpcCall call, size_t* result_len); /** * Get the result (return value) of a RPC call. This function blocks until * the result is received or it times out. + * * @param entry entry handle of RPC entry * @param call RPC call handle returned by NT_CallRpc() * @param result_len length of returned result in bytes @@ -895,6 +959,7 @@ char* NT_GetRpcResultTimeout(NT_Entry entry, NT_RpcCall call, /** * Ignore the result of a RPC call. This function is non-blocking. + * * @param entry entry handle of RPC entry * @param call RPC call handle returned by NT_CallRpc() */ @@ -902,6 +967,7 @@ void NT_CancelRpcResult(NT_Entry entry, NT_RpcCall call); /** * Pack a RPC version 1 definition. + * * @param def RPC version 1 definition * @param packed_len length of return value in bytes * @return Raw packed bytes. Use C standard library std::free() to release. @@ -912,6 +978,7 @@ char* NT_PackRpcDefinition(const struct NT_RpcDefinition* def, /** * Unpack a RPC version 1 definition. This can be used for introspection or * validation. + * * @param packed raw packed bytes * @param packed_len length of packed in bytes * @param def RPC version 1 definition (output) @@ -922,6 +989,7 @@ NT_Bool NT_UnpackRpcDefinition(const char* packed, size_t packed_len, /** * Pack RPC values as required for RPC version 1 definition messages. + * * @param values array of values to pack * @param values_len length of values * @param packed_len length of return value in bytes @@ -932,6 +1000,7 @@ char* NT_PackRpcValues(const struct NT_Value** values, size_t values_len, /** * Unpack RPC values as required for RPC version 1 definition messages. + * * @param packed raw packed bytes * @param packed_len length of packed in bytes * @param types array of data types (as provided in the RPC definition) @@ -945,7 +1014,7 @@ struct NT_Value** NT_UnpackRpcValues(const char* packed, size_t packed_len, /** @} */ /** - * @defgroup NetworkFunctions Client/Server Functions + * @defgroup ntcore_network_cfunc Client/Server Functions * @{ */ @@ -953,6 +1022,7 @@ struct NT_Value** NT_UnpackRpcValues(const char* packed, size_t packed_len, * Set the network identity of this node. * This is the name used during the initial connection handshake, and is * visible through NT_ConnectionInfo on the remote node. + * * @param inst instance handle * @param name identity to advertise * @param name_len length of name in bytes @@ -961,6 +1031,7 @@ void NT_SetNetworkIdentity(NT_Inst inst, const char* name, size_t name_len); /** * Get the current network mode. + * * @param inst instance handle * @return Bitmask of NT_NetworkMode. */ @@ -981,12 +1052,14 @@ void NT_StartServer(NT_Inst inst, const char* persist_filename, /** * Stops the server if it is running. + * * @param inst instance handle */ void NT_StopServer(NT_Inst inst); /** * Starts a client. Use NT_SetServer to set the server name and port. + * * @param inst instance handle */ void NT_StartClientNone(NT_Inst inst); @@ -1024,6 +1097,7 @@ void NT_StartClientTeam(NT_Inst inst, unsigned int team, unsigned int port); /** * Stops the client if it is running. + * * @param inst instance handle */ void NT_StopClient(NT_Inst inst); @@ -1072,6 +1146,7 @@ void NT_StartDSClient(NT_Inst inst, unsigned int port); /** * Stops requesting server address from Driver Station. + * * @param inst instance handle */ void NT_StopDSClient(NT_Inst inst); @@ -1087,6 +1162,7 @@ void NT_SetUpdateRate(NT_Inst inst, double interval); /** * Flush Entries. + * * Forces an immediate flush of all local entry changes to network. * Normally this is done on a regularly scheduled interval (see * NT_SetUpdateRate()). @@ -1114,6 +1190,7 @@ struct NT_ConnectionInfo* NT_GetConnections(NT_Inst inst, size_t* count); /** * Return whether or not the instance is connected to another node. + * * @param inst instance handle * @return True if connected. */ @@ -1122,7 +1199,7 @@ NT_Bool NT_IsConnected(NT_Inst inst); /** @} */ /** - * @defgroup FileFunctions File Save/Load Functions + * @defgroup ntcore_file_cfunc File Save/Load Functions * @{ */ @@ -1130,6 +1207,7 @@ NT_Bool NT_IsConnected(NT_Inst inst); * Save persistent values to a file. The server automatically does this, * but this function provides a way to save persistent values in the same * format to a file on either a client or a server. + * * @param inst instance handle * @param filename filename * @return error string, or NULL if successful @@ -1140,6 +1218,7 @@ const char* NT_SavePersistent(NT_Inst inst, const char* filename); * Load persistent values from a file. The server automatically does this * at startup, but this function provides a way to restore persistent values * in the same format from a file at any time on either a client or a server. + * * @param inst instance handle * @param filename filename * @param warn callback function for warnings @@ -1151,6 +1230,7 @@ const char* NT_LoadPersistent(NT_Inst inst, const char* filename, /** * Save table values to a file. The file format used is identical to * that used for SavePersistent. + * * @param inst instance handle * @param filename filename * @param prefix save only keys starting with this prefix @@ -1163,6 +1243,7 @@ const char* NT_SaveEntries(NT_Inst inst, const char* filename, /** * Load table values from a file. The file format used is identical to * that used for SavePersistent / LoadPersistent. + * * @param inst instance handle * @param filename filename * @param prefix load only keys starting with this prefix @@ -1177,12 +1258,13 @@ const char* NT_LoadEntries(NT_Inst inst, const char* filename, /** @} */ /** - * @defgroup UtilityFunctions Utility Functions + * @defgroup ntcore_utility_cfunc Utility Functions * @{ */ /** * Frees value memory. + * * @param value value to free */ void NT_DisposeValue(struct NT_Value* value); @@ -1190,12 +1272,14 @@ void NT_DisposeValue(struct NT_Value* value); /** * Initializes a NT_Value. * Sets type to NT_UNASSIGNED and clears rest of struct. + * * @param value value to initialize */ void NT_InitValue(struct NT_Value* value); /** * Frees string memory. + * * @param str string to free */ void NT_DisposeString(struct NT_String* str); @@ -1203,12 +1287,14 @@ void NT_DisposeString(struct NT_String* str); /** * Initializes a NT_String. * Sets length to zero and pointer to null. + * * @param str string to initialize */ void NT_InitString(struct NT_String* str); /** * Disposes an entry handle array. + * * @param arr pointer to the array to dispose * @param count number of elements in the array */ @@ -1216,6 +1302,7 @@ void NT_DisposeEntryArray(NT_Entry* arr, size_t count); /** * Disposes a connection info array. + * * @param arr pointer to the array to dispose * @param count number of elements in the array */ @@ -1223,6 +1310,7 @@ void NT_DisposeConnectionInfoArray(struct NT_ConnectionInfo* arr, size_t count); /** * Disposes an entry info array. + * * @param arr pointer to the array to dispose * @param count number of elements in the array */ @@ -1230,18 +1318,21 @@ void NT_DisposeEntryInfoArray(struct NT_EntryInfo* arr, size_t count); /** * Disposes a single entry info (as returned by NT_GetEntryInfoHandle). + * * @param info pointer to the info to dispose */ void NT_DisposeEntryInfo(struct NT_EntryInfo* info); /** * Disposes a Rpc Definition structure. + * * @param def pointer to the struct to dispose */ void NT_DisposeRpcDefinition(struct NT_RpcDefinition* def); /** * Disposes a Rpc Answer array. + * * @param arr pointer to the array to dispose * @param count number of elements in the array */ @@ -1249,12 +1340,14 @@ void NT_DisposeRpcAnswerArray(struct NT_RpcAnswer* arr, size_t count); /** * Disposes a Rpc Answer structure. + * * @param answer pointer to the struct to dispose */ void NT_DisposeRpcAnswer(struct NT_RpcAnswer* answer); /** * Disposes an entry notification array. + * * @param arr pointer to the array to dispose * @param count number of elements in the array */ @@ -1263,12 +1356,14 @@ void NT_DisposeEntryNotificationArray(struct NT_EntryNotification* arr, /** * Disposes a single entry notification. + * * @param info pointer to the info to dispose */ void NT_DisposeEntryNotification(struct NT_EntryNotification* info); /** * Disposes a connection notification array. + * * @param arr pointer to the array to dispose * @param count number of elements in the array */ @@ -1277,12 +1372,14 @@ void NT_DisposeConnectionNotificationArray( /** * Disposes a single connection notification. + * * @param info pointer to the info to dispose */ void NT_DisposeConnectionNotification(struct NT_ConnectionNotification* info); /** * Disposes a log message array. + * * @param arr pointer to the array to dispose * @param count number of elements in the array */ @@ -1290,6 +1387,7 @@ void NT_DisposeLogMessageArray(struct NT_LogMessage* arr, size_t count); /** * Disposes a single log message. + * * @param info pointer to the info to dispose */ void NT_DisposeLogMessage(struct NT_LogMessage* info); @@ -1298,6 +1396,7 @@ void NT_DisposeLogMessage(struct NT_LogMessage* info); * Returns monotonic current time in 1 us increments. * This is the same time base used for entry and connection timestamps. * This function is a compatibility wrapper around WPI_Now(). + * * @return Timestamp */ uint64_t NT_Now(void); @@ -1305,12 +1404,13 @@ uint64_t NT_Now(void); /** @} */ /** - * @defgroup LoggerFunctions Logger Functions + * @defgroup ntcore_logger_cfunc Logger Functions * @{ */ /** * Log function. + * * @param data data pointer passed to NT_AddLogger() * @param msg message information */ @@ -1336,6 +1436,7 @@ NT_Logger NT_AddLogger(NT_Inst inst, void* data, NT_LogFunc func, /** * Create a log poller. A poller provides a single queue of poll events. * The returned handle must be destroyed with NT_DestroyLoggerPoller(). + * * @param inst instance handle * @return poller handle */ @@ -1344,6 +1445,7 @@ NT_LoggerPoller NT_CreateLoggerPoller(NT_Inst inst); /** * Destroy a log poller. This will abort any blocked polling call and prevent * additional events from being generated for this poller. + * * @param poller poller handle */ void NT_DestroyLoggerPoller(NT_LoggerPoller poller); @@ -1352,6 +1454,7 @@ void NT_DestroyLoggerPoller(NT_LoggerPoller poller); * Set the log level for a log poller. Events will only be generated for * log messages with level greater than or equal to min_level and less than or * equal to max_level; messages outside this range will be silently ignored. + * * @param poller poller handle * @param min_level minimum log level * @param max_level maximum log level @@ -1362,6 +1465,7 @@ NT_Logger NT_AddPolledLogger(NT_LoggerPoller poller, unsigned int min_level, /** * Get the next log event. This blocks until the next log occurs. + * * @param poller poller handle * @param len length of returned array (output) * @return Array of information on the log events. Only returns NULL if an @@ -1372,6 +1476,7 @@ struct NT_LogMessage* NT_PollLogger(NT_LoggerPoller poller, size_t* len); /** * Get the next log event. This blocks until the next log occurs or it times * out. + * * @param poller poller handle * @param len length of returned array (output) * @param timeout timeout, in seconds @@ -1386,12 +1491,14 @@ struct NT_LogMessage* NT_PollLoggerTimeout(NT_LoggerPoller poller, size_t* len, /** * Cancel a PollLogger call. This wakes up a call to PollLogger for this * poller and causes it to immediately return an empty array. + * * @param poller poller handle */ void NT_CancelPollLogger(NT_LoggerPoller poller); /** * Remove a logger. + * * @param logger Logger handle to remove */ void NT_RemoveLogger(NT_Logger logger); @@ -1401,6 +1508,7 @@ void NT_RemoveLogger(NT_Logger logger); * for deterministic testing. This blocks until either the log event * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param inst instance handle * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely @@ -1411,12 +1519,12 @@ NT_Bool NT_WaitForLoggerQueue(NT_Inst inst, double timeout); /** @} */ /** - * @defgroup InteropFunctions Interop Utility Functions + * @defgroup ntcore_interop_cfunc Interop Utility Functions * @{ */ /** - * @defgroup MemoryAllocators Memory Allocators + * @defgroup ntcore_memoryallocators_cfunc Memory Allocators * @{ */ @@ -1508,7 +1616,7 @@ void NT_FreeStringArray(struct NT_String* v_string, size_t arr_size); /** @} */ /** - * @defgroup TypedGetters Typed Getters + * @defgroup ntcore_typedgetters_cfunc Typed Getters * @{ */ @@ -1745,7 +1853,7 @@ struct NT_String* NT_GetEntryStringArray(NT_Entry entry, uint64_t* last_change, /** @} */ /** - * @defgroup SetDefault Set Default Values + * @defgroup ntcore_setdefault_cfunc Set Default Values * @{ */ @@ -1851,7 +1959,7 @@ NT_Bool NT_SetDefaultEntryStringArray(NT_Entry entry, uint64_t time, /** @} */ /** - * @defgroup ValueSetters Entry Value Setters + * @defgroup ntcore_valuesetters_cfunc Entry Value Setters * @{ */ @@ -1954,6 +2062,7 @@ NT_Bool NT_SetEntryStringArray(NT_Entry entry, uint64_t time, /** @} */ /** @} */ +/** @} */ #ifdef __cplusplus } // extern "C" diff --git a/ntcore/src/main/native/include/ntcore_cpp.h b/ntcore/src/main/native/include/ntcore_cpp.h index 0d729a17a4..2683d4a89f 100644 --- a/ntcore/src/main/native/include/ntcore_cpp.h +++ b/ntcore/src/main/native/include/ntcore_cpp.h @@ -27,6 +27,14 @@ namespace nt { +/** + * @defgroup ntcore_cpp_handle_api ntcore C++ API + * + * Handle-based interface for C++. + * + * @{ + */ + using wpi::ArrayRef; using wpi::StringRef; using wpi::Twine; @@ -272,19 +280,21 @@ class LogMessage { }; /** - * @defgroup InstanceFunctions Instance Functions + * @defgroup ntcore_instance_func Instance Functions * @{ */ /** * Get default instance. * This is the instance used by non-handle-taking functions. + * * @return Instance handle */ NT_Inst GetDefaultInstance(); /** * Create an instance. + * * @return Instance handle */ NT_Inst CreateInstance(); @@ -292,12 +302,14 @@ NT_Inst CreateInstance(); /** * Destroy an instance. * The default instance cannot be destroyed. + * * @param inst Instance handle */ void DestroyInstance(NT_Inst inst); /** * Get instance handle from another handle. + * * @param handle entry/instance/etc. handle * @return Instance handle */ @@ -306,12 +318,13 @@ NT_Inst GetInstanceFromHandle(NT_Handle handle); /** @} */ /** - * @defgroup TableFunctions Table Functions + * @defgroup ntcore_table_func Table Functions * @{ */ /** * Get Entry Handle. + * * @param inst instance handle * @param name entry name (UTF-8 string) * @return entry handle @@ -320,6 +333,7 @@ NT_Entry GetEntry(NT_Inst inst, const Twine& name); /** * Get Entry Handles. + * * Returns an array of entry handles. The results are optionally * filtered by string prefix and entry type to only return a subset of all * entries. @@ -337,6 +351,7 @@ std::vector GetEntries(NT_Inst inst, const Twine& prefix, /** * Gets the name of the specified entry. * Returns an empty string if the handle is invalid. + * * @param entry entry handle * @return Entry name */ @@ -344,6 +359,7 @@ std::string GetEntryName(NT_Entry entry); /** * Gets the type for the specified entry, or unassigned if non existent. + * * @param entry entry handle * @return Entry type */ @@ -352,6 +368,7 @@ NT_Type GetEntryType(NT_Entry entry); /** * Gets the last time the entry was changed. * Returns 0 if the handle is invalid. + * * @param entry entry handle * @return Entry last change time */ @@ -359,6 +376,7 @@ uint64_t GetEntryLastChange(NT_Entry entry); /** * Get Entry Value. + * * Returns copy of current entry value. * Note that one of the type options is "unassigned". * @@ -370,6 +388,7 @@ std::shared_ptr GetEntryValue(StringRef name); /** * Get Entry Value. + * * Returns copy of current entry value. * Note that one of the type options is "unassigned". * @@ -380,6 +399,7 @@ std::shared_ptr GetEntryValue(NT_Entry entry); /** * Set Default Entry Value + * * Returns copy of current entry value if it exists. * Otherwise, sets passed in value, and returns set value. * Note that one of the type options is "unassigned". @@ -393,6 +413,7 @@ bool SetDefaultEntryValue(StringRef name, std::shared_ptr value); /** * Set Default Entry Value + * * Returns copy of current entry value if it exists. * Otherwise, sets passed in value, and returns set value. * Note that one of the type options is "unassigned". @@ -405,6 +426,7 @@ bool SetDefaultEntryValue(NT_Entry entry, std::shared_ptr value); /** * Set Entry Value. + * * Sets new entry value. If type of new value differs from the type of the * currently stored entry, returns error and does not update value. * @@ -417,6 +439,7 @@ bool SetEntryValue(StringRef name, std::shared_ptr value); /** * Set Entry Value. + * * Sets new entry value. If type of new value differs from the type of the * currently stored entry, returns error and does not update value. * @@ -428,6 +451,7 @@ bool SetEntryValue(NT_Entry entry, std::shared_ptr value); /** * Set Entry Type and Value. + * * Sets new entry value. If type of new value differs from the type of the * currently stored entry, the currently stored entry type is overridden * (generally this will generate an Entry Assignment message). @@ -443,6 +467,7 @@ void SetEntryTypeValue(StringRef name, std::shared_ptr value); /** * Set Entry Type and Value. + * * Sets new entry value. If type of new value differs from the type of the * currently stored entry, the currently stored entry type is overridden * (generally this will generate an Entry Assignment message). @@ -457,6 +482,7 @@ void SetEntryTypeValue(NT_Entry entry, std::shared_ptr value); /** * Set Entry Flags. + * * @param name entry name (UTF-8 string) * @param flags flags value (bitmask of NT_EntryFlags) */ @@ -465,6 +491,7 @@ void SetEntryFlags(StringRef name, unsigned int flags); /** * Set Entry Flags. + * * @param entry entry handle * @param flags flags value (bitmask of NT_EntryFlags) */ @@ -472,6 +499,7 @@ void SetEntryFlags(NT_Entry entry, unsigned int flags); /** * Get Entry Flags. + * * @param name entry name (UTF-8 string) * @return Flags value (bitmask of NT_EntryFlags) */ @@ -480,6 +508,7 @@ unsigned int GetEntryFlags(StringRef name); /** * Get Entry Flags. + * * @param entry entry handle * @return Flags value (bitmask of NT_EntryFlags) */ @@ -487,6 +516,7 @@ unsigned int GetEntryFlags(NT_Entry entry); /** * Delete Entry. + * * Deletes an entry. This is a new feature in version 3.0 of the protocol, * so this may not have an effect if any other node in the network is not * version 3.0 or newer. @@ -502,6 +532,7 @@ void DeleteEntry(StringRef name); /** * Delete Entry. + * * Deletes an entry. This is a new feature in version 3.0 of the protocol, * so this may not have an effect if any other node in the network is not * version 3.0 or newer. @@ -516,6 +547,7 @@ void DeleteEntry(NT_Entry entry); /** * Delete All Entries. + * * Deletes ALL table entries. This is a new feature in version 3.0 of the * so this may not have an effect if any other node in the network is not * version 3.0 or newer. @@ -536,6 +568,7 @@ void DeleteAllEntries(NT_Inst inst); /** * Get Entry Information. + * * Returns an array of entry information (name, entry type, * and timestamp of last change to type/value). The results are optionally * filtered by string prefix and entry type to only return a subset of all @@ -560,6 +593,7 @@ std::vector GetEntryInfo(NT_Inst inst, const Twine& prefix, /** * Get Entry Information. + * * Returns information about an entry (name, entry type, * and timestamp of last change to type/value). * @@ -571,7 +605,7 @@ EntryInfo GetEntryInfo(NT_Entry entry); /** @} */ /** - * @defgroup EntryListenerFunctions Entry Listener Functions + * @defgroup ntcore_entrylistener_func Entry Listener Functions * @{ */ @@ -605,6 +639,7 @@ NT_EntryListener AddEntryListener(StringRef prefix, /** * @copydoc AddEntryListener(StringRef, EntryListenerCallback, unsigned int) + * * @param inst instance handle */ NT_EntryListener AddEntryListener( @@ -627,10 +662,12 @@ NT_EntryListener AddEntryListener( /** * Create a entry listener poller. + * * A poller provides a single queue of poll events. Events linked to this * poller (using AddPolledEntryListener()) will be stored in the queue and * must be collected by calling PollEntryListener(). * The returned handle must be destroyed with DestroyEntryListenerPoller(). + * * @param inst instance handle * @return poller handle */ @@ -639,6 +676,7 @@ NT_EntryListenerPoller CreateEntryListenerPoller(NT_Inst inst); /** * Destroy a entry listener poller. This will abort any blocked polling * call and prevent additional events from being generated for this poller. + * * @param poller poller handle */ void DestroyEntryListenerPoller(NT_EntryListenerPoller poller); @@ -646,6 +684,7 @@ void DestroyEntryListenerPoller(NT_EntryListenerPoller poller); /** * Create a polled entry listener. * The caller is responsible for calling PollEntryListener() to poll. + * * @param poller poller handle * @param prefix UTF-8 string prefix * @param flags NotifyKind bitmask @@ -658,6 +697,7 @@ NT_EntryListener AddPolledEntryListener(NT_EntryListenerPoller poller, /** * Create a polled entry listener. * The caller is responsible for calling PollEntryListener() to poll. + * * @param poller poller handle * @param prefix UTF-8 string prefix * @param flags NotifyKind bitmask @@ -670,6 +710,7 @@ NT_EntryListener AddPolledEntryListener(NT_EntryListenerPoller poller, * Get the next entry listener event. This blocks until the next event occurs. * This is intended to be used with AddPolledEntryListener(); entry listeners * created using AddEntryListener() will not be serviced through this function. + * * @param poller poller handle * @return Information on the entry listener events. Only returns empty if an * error occurred (e.g. the instance was invalid or is shutting down). @@ -681,6 +722,7 @@ std::vector PollEntryListener(NT_EntryListenerPoller poller); * or it times out. This is intended to be used with AddPolledEntryListener(); * entry listeners created using AddEntryListener() will not be serviced * through this function. + * * @param poller poller handle * @param timeout timeout, in seconds * @param timed_out true if the timeout period elapsed (output) @@ -696,12 +738,14 @@ std::vector PollEntryListener(NT_EntryListenerPoller poller, * Cancel a PollEntryListener call. This wakes up a call to * PollEntryListener for this poller and causes it to immediately return * an empty array. + * * @param poller poller handle */ void CancelPollEntryListener(NT_EntryListenerPoller poller); /** * Remove an entry listener. + * * @param entry_listener Listener handle to remove */ void RemoveEntryListener(NT_EntryListener entry_listener); @@ -711,6 +755,7 @@ void RemoveEntryListener(NT_EntryListener entry_listener); * for deterministic testing. This blocks until either the entry listener * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param inst instance handle * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely @@ -721,7 +766,7 @@ bool WaitForEntryListenerQueue(NT_Inst inst, double timeout); /** @} */ /** - * @defgroup ConnectionListenerFunctions Connection Listener Functions + * @defgroup ntcore_connectionlistener_func Connection Listener Functions * @{ */ @@ -751,6 +796,7 @@ NT_ConnectionListener AddConnectionListener(ConnectionListenerCallback callback, /** * @copydoc AddConnectionListener(ConnectionListenerCallback, bool) + * * @param inst instance handle */ NT_ConnectionListener AddConnectionListener( @@ -760,10 +806,12 @@ NT_ConnectionListener AddConnectionListener( /** * Create a connection listener poller. + * * A poller provides a single queue of poll events. Events linked to this * poller (using AddPolledConnectionListener()) will be stored in the queue and * must be collected by calling PollConnectionListener(). * The returned handle must be destroyed with DestroyConnectionListenerPoller(). + * * @param inst instance handle * @return poller handle */ @@ -772,6 +820,7 @@ NT_ConnectionListenerPoller CreateConnectionListenerPoller(NT_Inst inst); /** * Destroy a connection listener poller. This will abort any blocked polling * call and prevent additional events from being generated for this poller. + * * @param poller poller handle */ void DestroyConnectionListenerPoller(NT_ConnectionListenerPoller poller); @@ -779,6 +828,7 @@ void DestroyConnectionListenerPoller(NT_ConnectionListenerPoller poller); /** * Create a polled connection listener. * The caller is responsible for calling PollConnectionListener() to poll. + * * @param poller poller handle * @param immediate_notify notify listener of all existing connections */ @@ -790,6 +840,7 @@ NT_ConnectionListener AddPolledConnectionListener( * disconnect occurs. This is intended to be used with * AddPolledConnectionListener(); connection listeners created using * AddConnectionListener() will not be serviced through this function. + * * @param poller poller handle * @return Information on the connection events. Only returns empty if an * error occurred (e.g. the instance was invalid or is shutting down). @@ -802,6 +853,7 @@ std::vector PollConnectionListener( * disconnect occurs or it times out. This is intended to be used with * AddPolledConnectionListener(); connection listeners created using * AddConnectionListener() will not be serviced through this function. + * * @param poller poller handle * @param timeout timeout, in seconds * @param timed_out true if the timeout period elapsed (output) @@ -816,12 +868,14 @@ std::vector PollConnectionListener( * Cancel a PollConnectionListener call. This wakes up a call to * PollConnectionListener for this poller and causes it to immediately return * an empty array. + * * @param poller poller handle */ void CancelPollConnectionListener(NT_ConnectionListenerPoller poller); /** * Remove a connection listener. + * * @param conn_listener Listener handle to remove */ void RemoveConnectionListener(NT_ConnectionListener conn_listener); @@ -831,6 +885,7 @@ void RemoveConnectionListener(NT_ConnectionListener conn_listener); * for deterministic testing. This blocks until either the connection listener * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param inst instance handle * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely @@ -841,13 +896,14 @@ bool WaitForConnectionListenerQueue(NT_Inst inst, double timeout); /** @} */ /** - * @defgroup RpcFunctions Remote Procedure Call Functions + * @defgroup ntcore_rpc_func Remote Procedure Call Functions * @{ */ /** * Create a callback-based RPC entry point. Only valid to use on the server. * The callback function will be called when the RPC is called. + * * @param entry entry handle of RPC entry * @param def RPC definition * @param callback callback function; note the callback function must call @@ -858,10 +914,12 @@ void CreateRpc(NT_Entry entry, StringRef def, /** * Create a RPC call poller. Only valid to use on the server. + * * A poller provides a single queue of poll events. Events linked to this * poller (using CreatePolledRpc()) will be stored in the queue and must be * collected by calling PollRpc(). * The returned handle must be destroyed with DestroyRpcCallPoller(). + * * @param inst instance handle * @return poller handle */ @@ -870,6 +928,7 @@ NT_RpcCallPoller CreateRpcCallPoller(NT_Inst inst); /** * Destroy a RPC call poller. This will abort any blocked polling call and * prevent additional events from being generated for this poller. + * * @param poller poller handle */ void DestroyRpcCallPoller(NT_RpcCallPoller poller); @@ -878,6 +937,7 @@ void DestroyRpcCallPoller(NT_RpcCallPoller poller); * Create a polled RPC entry point. Only valid to use on the server. * The caller is responsible for calling PollRpc() to poll for servicing * incoming RPC calls. + * * @param entry entry handle of RPC entry * @param def RPC definition * @param poller poller handle @@ -890,6 +950,7 @@ void CreatePolledRpc(NT_Entry entry, StringRef def, NT_RpcCallPoller poller); * RPC calls created using CreateRpc() will not be serviced through this * function. Upon successful return, PostRpcResponse() must be called to * send the return value to the caller. + * * @param poller poller handle * @return Information on the next RPC calls. Only returns empty if an error * occurred (e.g. the instance was invalid or is shutting down). @@ -902,6 +963,7 @@ std::vector PollRpc(NT_RpcCallPoller poller); * CreatePolledRpc(); RPC calls created using CreateRpc() will not be * serviced through this function. Upon successful return, * PostRpcResponse() must be called to send the return value to the caller. + * * @param poller poller handle * @param timeout timeout, in seconds * @param timed_out true if the timeout period elapsed (output) @@ -915,6 +977,7 @@ std::vector PollRpc(NT_RpcCallPoller poller, double timeout, /** * Cancel a PollRpc call. This wakes up a call to PollRpc for this poller * and causes it to immediately return an empty array. + * * @param poller poller handle */ void CancelPollRpc(NT_RpcCallPoller poller); @@ -924,6 +987,7 @@ void CancelPollRpc(NT_RpcCallPoller poller); * for deterministic testing. This blocks until either the RPC call * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param inst instance handle * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely @@ -935,6 +999,7 @@ bool WaitForRpcCallQueue(NT_Inst inst, double timeout); * Post RPC response (return value) for a polled RPC. * The rpc and call parameters should come from the RpcAnswer returned * by PollRpc(). + * * @param entry entry handle of RPC entry (from RpcAnswer) * @param call RPC call handle (from RpcAnswer) * @param result result raw data that will be provided to remote caller @@ -947,6 +1012,7 @@ bool PostRpcResponse(NT_Entry entry, NT_RpcCall call, StringRef result); * This function is non-blocking. Either GetRpcResult() or * CancelRpcResult() must be called to either get or ignore the result of * the call. + * * @param entry entry handle of RPC entry * @param params parameter * @return RPC call handle (for use with GetRpcResult() or @@ -957,6 +1023,7 @@ NT_RpcCall CallRpc(NT_Entry entry, StringRef params); /** * Get the result (return value) of a RPC call. This function blocks until * the result is received. + * * @param entry entry handle of RPC entry * @param call RPC call handle returned by CallRpc() * @param result received result (output) @@ -967,6 +1034,7 @@ bool GetRpcResult(NT_Entry entry, NT_RpcCall call, std::string* result); /** * Get the result (return value) of a RPC call. This function blocks until * the result is received or it times out. + * * @param entry entry handle of RPC entry * @param call RPC call handle returned by CallRpc() * @param result received result (output) @@ -979,6 +1047,7 @@ bool GetRpcResult(NT_Entry entry, NT_RpcCall call, std::string* result, /** * Ignore the result of a RPC call. This function is non-blocking. + * * @param entry entry handle of RPC entry * @param call RPC call handle returned by CallRpc() */ @@ -986,6 +1055,7 @@ void CancelRpcResult(NT_Entry entry, NT_RpcCall call); /** * Pack a RPC version 1 definition. + * * @param def RPC version 1 definition * @return Raw packed bytes. */ @@ -994,6 +1064,7 @@ std::string PackRpcDefinition(const RpcDefinition& def); /** * Unpack a RPC version 1 definition. This can be used for introspection or * validation. + * * @param packed raw packed bytes * @param def RPC version 1 definition (output) * @return True if successfully unpacked, false otherwise. @@ -1002,6 +1073,7 @@ bool UnpackRpcDefinition(StringRef packed, RpcDefinition* def); /** * Pack RPC values as required for RPC version 1 definition messages. + * * @param values array of values to pack * @return Raw packed bytes. */ @@ -1009,6 +1081,7 @@ std::string PackRpcValues(ArrayRef> values); /** * Unpack RPC values as required for RPC version 1 definition messages. + * * @param packed raw packed bytes * @param types array of data types (as provided in the RPC definition) * @return Array of values. @@ -1019,7 +1092,7 @@ std::vector> UnpackRpcValues(StringRef packed, /** @} */ /** - * @defgroup NetworkFunctions Client/Server Functions + * @defgroup ntcore_network_func Client/Server Functions * @{ */ @@ -1027,6 +1100,7 @@ std::vector> UnpackRpcValues(StringRef packed, * Set the network identity of this node. * This is the name used during the initial connection handshake, and is * visible through ConnectionInfo on the remote node. + * * @param name identity to advertise */ WPI_DEPRECATED("use NT_Inst function instead") @@ -1034,12 +1108,14 @@ void SetNetworkIdentity(StringRef name); /** * @copydoc SetNetworkIdentity(StringRef) + * * @param inst instance handle */ void SetNetworkIdentity(NT_Inst inst, const Twine& name); /** * Get the current network mode. + * * @return Bitmask of NT_NetworkMode. */ WPI_DEPRECATED("use NT_Inst function instead") @@ -1047,6 +1123,7 @@ unsigned int GetNetworkMode(); /** * Get the current network mode. + * * @param inst instance handle * @return Bitmask of NT_NetworkMode. */ @@ -1067,6 +1144,7 @@ void StartServer(StringRef persist_filename, const char* listen_address, /** * @copydoc StartServer(StringRef, const char*, unsigned int) + * * @param inst instance handle */ void StartServer(NT_Inst inst, const Twine& persist_filename, @@ -1080,6 +1158,7 @@ void StopServer(); /** * @copydoc StopServer() + * * @param inst instance handle */ void StopServer(NT_Inst inst); @@ -1110,18 +1189,21 @@ void StartClient(ArrayRef> servers); /** * @copydoc StartClient() + * * @param inst instance handle */ void StartClient(NT_Inst inst); /** * @copydoc StartClient(const char*, unsigned int) + * * @param inst instance handle */ void StartClient(NT_Inst inst, const char* server_name, unsigned int port); /** * @copydoc StartClient(ArrayRef>) + * * @param inst instance handle */ void StartClient(NT_Inst inst, @@ -1169,12 +1251,14 @@ void SetServer(ArrayRef> servers); /** * @copydoc SetServer(const char*, unsigned int) + * * @param inst instance handle */ void SetServer(NT_Inst inst, const char* server_name, unsigned int port); /** * @copydoc SetServer(ArrayRef>) + * * @param inst instance handle */ void SetServer(NT_Inst inst, @@ -1212,6 +1296,7 @@ void StopDSClient(); /** * @copydoc StopDSClient() + * * @param inst instance handle */ void StopDSClient(NT_Inst inst); @@ -1231,12 +1316,14 @@ void SetUpdateRate(double interval); /** * @copydoc SetUpdateRate(double) + * * @param inst instance handle */ void SetUpdateRate(NT_Inst inst, double interval); /** * Flush Entries. + * * Forces an immediate flush of all local entry changes to network. * Normally this is done on a regularly scheduled interval (see * SetUpdateRate()). @@ -1266,12 +1353,14 @@ std::vector GetConnections(); /** * @copydoc GetConnections() + * * @param inst instance handle */ std::vector GetConnections(NT_Inst inst); /** * Return whether or not the instance is connected to another node. + * * @param inst instance handle * @return True if connected. */ @@ -1280,7 +1369,7 @@ bool IsConnected(NT_Inst inst); /** @} */ /** - * @defgroup FileFunctions File Save/Load Functions + * @defgroup ntcore_file_func File Save/Load Functions * @{ */ @@ -1288,6 +1377,7 @@ bool IsConnected(NT_Inst inst); * Save persistent values to a file. The server automatically does this, * but this function provides a way to save persistent values in the same * format to a file on either a client or a server. + * * @param filename filename * @return error string, or nullptr if successful */ @@ -1304,6 +1394,7 @@ const char* SavePersistent(NT_Inst inst, const Twine& filename); * Load persistent values from a file. The server automatically does this * at startup, but this function provides a way to restore persistent values * in the same format from a file at any time on either a client or a server. + * * @param filename filename * @param warn callback function for warnings * @return error string, or nullptr if successful @@ -1315,6 +1406,7 @@ const char* LoadPersistent( /** * @copydoc LoadPersistent(StringRef, std::function) + * * @param inst instance handle */ const char* LoadPersistent( @@ -1324,6 +1416,7 @@ const char* LoadPersistent( /** * Save table values to a file. The file format used is identical to * that used for SavePersistent. + * * @param inst instance handle * @param filename filename * @param prefix save only keys starting with this prefix @@ -1335,6 +1428,7 @@ const char* SaveEntries(NT_Inst inst, const Twine& filename, /** * Load table values from a file. The file format used is identical to * that used for SavePersistent / LoadPersistent. + * * @param inst instance handle * @param filename filename * @param prefix load only keys starting with this prefix @@ -1348,7 +1442,7 @@ const char* LoadEntries(NT_Inst inst, const Twine& filename, /** @} */ /** - * @defgroup UtilityFunctions Utility Functions + * @defgroup ntcore_utility_func Utility Functions * @{ */ @@ -1356,6 +1450,7 @@ const char* LoadEntries(NT_Inst inst, const Twine& filename, * Returns monotonic current time in 1 us increments. * This is the same time base used for entry and connection timestamps. * This function is a compatibility wrapper around wpi::Now(). + * * @return Timestamp */ uint64_t Now(); @@ -1363,12 +1458,13 @@ uint64_t Now(); /** @} */ /** - * @defgroup LoggerFunctions Logger Functions + * @defgroup ntcore_logger_func Logger Functions * @{ */ /** * Log function. + * * @param level log level of the message (see NT_LogLevel) * @param file origin source filename * @param line origin source line number @@ -1411,6 +1507,7 @@ NT_Logger AddLogger(NT_Inst inst, /** * Create a log poller. A poller provides a single queue of poll events. * The returned handle must be destroyed with DestroyLoggerPoller(). + * * @param inst instance handle * @return poller handle */ @@ -1419,6 +1516,7 @@ NT_LoggerPoller CreateLoggerPoller(NT_Inst inst); /** * Destroy a log poller. This will abort any blocked polling call and prevent * additional events from being generated for this poller. + * * @param poller poller handle */ void DestroyLoggerPoller(NT_LoggerPoller poller); @@ -1427,6 +1525,7 @@ void DestroyLoggerPoller(NT_LoggerPoller poller); * Set the log level for a log poller. Events will only be generated for * log messages with level greater than or equal to min_level and less than or * equal to max_level; messages outside this range will be silently ignored. + * * @param poller poller handle * @param min_level minimum log level * @param max_level maximum log level @@ -1437,6 +1536,7 @@ NT_Logger AddPolledLogger(NT_LoggerPoller poller, unsigned int min_level, /** * Get the next log event. This blocks until the next log occurs. + * * @param poller poller handle * @return Information on the log events. Only returns empty if an error * occurred (e.g. the instance was invalid or is shutting down). @@ -1446,6 +1546,7 @@ std::vector PollLogger(NT_LoggerPoller poller); /** * Get the next log event. This blocks until the next log occurs or it times * out. + * * @param poller poller handle * @param timeout timeout, in seconds * @param timed_out true if the timeout period elapsed (output) @@ -1459,12 +1560,14 @@ std::vector PollLogger(NT_LoggerPoller poller, double timeout, /** * Cancel a PollLogger call. This wakes up a call to PollLogger for this * poller and causes it to immediately return an empty array. + * * @param poller poller handle */ void CancelPollLogger(NT_LoggerPoller poller); /** * Remove a logger. + * * @param logger Logger handle to remove */ void RemoveLogger(NT_Logger logger); @@ -1474,6 +1577,7 @@ void RemoveLogger(NT_Logger logger); * for deterministic testing. This blocks until either the log event * queue is empty (e.g. there are no more events that need to be passed along * to callbacks or poll queues) or the timeout expires. + * * @param inst instance handle * @param timeout timeout, in seconds. Set to 0 for non-blocking behavior, * or a negative value to block indefinitely @@ -1481,6 +1585,7 @@ void RemoveLogger(NT_Logger logger); */ bool WaitForLoggerQueue(NT_Inst inst, double timeout); +/** @} */ /** @} */ inline bool RpcAnswer::PostResponse(StringRef result) const {