SmartDashboard.setDefault* documentation

[chauser]

I would like to address #6334, but realized that some discussion about how the behavior should be documented would help before changing all of them. The code diff here contains a proposal that reflects my understanding of the actual behavior.

Questions:

1. Would you suggest different wording for documenting the behavior of these methods?
2. Should documentation in NetworkTableEntry.java, NetworkTablesJNI.java, ntcore_c.h, and ntcore_cpp.h also be addressed in the same PR, or in a second PR specific to the ntcore component?

More details about NetworkTableEntry.java, NetworkTablesJNI.java, ntcore_c.h, and ntcore_cpp.h:

SetDefault* methods in NetworkTableEntry.java called by SmartDashboard.setDefault* document the return value as @return False if the entry exists with a different type whereas the actual behavior is @return False if the entry exists. Interestingly, the descriptive documentation here is Sets the entry's value if it does not exist. which is correct.

The next level down is NetworkTablesJNI.java. Here the documentation is

/**
   * Sets default topic value.
   *
   * @param entry Entry handle.
   * @param time Time in microseconds.
   * @param defaultValue Default value.
   * @return True if set succeeded.
   */

which is correct but doesn't identify criteria for success.

On the C/C++ side:

ntcore_c.h has

/**
 * 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".
 *
 * @param entry     entry handle
 * @param default_value     value to be set if name does not exist
 * @return 0 on error (value not set), 1 on success
 */

having both the "Returns a copy of..." error and lack of specificity about success. ntcore_cpp.h has essentially the same issues as ntcore_c.h.

[chauser]

/format

[rzblue]

SmartDashboard.h needs to be fixed similar to java everywhere it says this:

Gets the current value in the table, setting it if it does not exist.

[rzblue]

Suggested change

	* @return True: success; False the key already existed
	* @return True if the key did not already exist, otherwise false

ditto for all others for consistency

[rzblue]

Should documentation in NetworkTableEntry.java, NetworkTablesJNI.java, ntcore_c.h, and ntcore_cpp.h also be addressed in the same PR, or in a second PR specific to the ntcore component?

Addressing them in the same PR would be fine

Would you suggest different wording for documenting the behavior of these methods?

I think an appropriate wording would be

Sets the entry's (or "topic", as appropriate) value if it does not exist. Returns true if the value did not already exist, otherwise false.

[chauser]

Still WIP

[chauser]

I think this is ready for re-review. While I was fixing SmartDashboard.h I noticed that the Get* methods also were erroneous in saying that their defaultValue would be "set" if the key was not in the table, so I fixed those too.

Resolved