📝 PROS 4: Documentation Fixes for optical and distance sensor (#654)

* Documentation Fixes for optical sensor

* Distance sensor documentation fixes

* Added alias function get_distance for get for distance sensor

* Update get_distance func header for distance sensor

include/pros/distance.hpp

@@ -70,7 +70,7 @@ class Distance : public Device {
 	 * ENODEV - The port cannot be configured as an Distance Sensor
 	 *
 	 * \return The distance value or PROS_ERR if the operation failed, setting
-	 * errno.
+	 * errno. Will return 9999 if the sensor can not detect an object.
 	 *
 	 * \b Example
 	 * \code
@@ -89,6 +89,33 @@ class Distance : public Device {
 
 	static std::vector<Distance> get_all_devices();
 
+	/**
+	 * Get the currently measured distance from the sensor in mm.
+	 * \note This function is identical to get().
+	 *
+	 * This function uses the following values of errno when an error state is
+	 * reached:
+	 * ENXIO - The given value is not within the range of V5 ports (1-21).
+	 * ENODEV - The port cannot be configured as an Distance Sensor
+	 *
+	 * \return The distance value or PROS_ERR if the operation failed, setting
+	 * errno. Will return 9999 if the sensor can not detect an object.
+	 *
+	 * \b Example
+	 * \code
+	 * #define DISTANCE_PORT 1
+	 * 
+	 * void opcontrol() {
+		Distance distance(DISTANCE_PORT);
+	 *   while (true) {
+	 *     printf("Distance confidence: %d\n", distance.get_distance());
+	 *     delay(20);
+	 *   }
+	 * }
+	 * \endcode
+	 */
+	virtual std::int32_t get_distance();
+
 	/**
 	 * Get the confidence in the distance reading
 	 *
@@ -132,7 +159,7 @@ class Distance : public Device {
 	 * ENODEV - The port cannot be configured as an Distance Sensor
 	 *
 	 * \return The size value or PROS_ERR if the operation failed, setting
-	 * errno.
+	 * errno. Will return -1 if the sensor is not able to determine object size.
 	 *
 	 * \b Example
 	 * \code

include/pros/optical.hpp

@@ -129,6 +129,7 @@ class Optical : public Device {
 	 * 		pros::Optical optical(1);
 	 * 		std::cout << "Brightness: " << optical.get_brightness() << std::endl;
 	 * }
+	 * \endcode
 	 */
 	virtual double get_brightness();
 
@@ -240,17 +241,33 @@ class Optical : public Device {
 	 *
 	 * \return raw rgb value if the operation was successful or an optical_raw_s_t 
 	 * with all fields set to PROS_ERR if the operation failed, setting errno.
+	 * 
+	 * \b Example:
+	 * \code{.cpp}
+	 * void opcontrol() {
+	 * 		pros::Optical optical(1);
+	 * 		pros::c::optical_raw_s_t raw = optical.get_raw();
+	 * 		while (1) {
+	 * 			std::cout << "Red: " << raw.red << std::endl;
+	 * 			std::cout << "Green: " << raw.green << std::endl;
+	 * 			std::cout << "Blue: " << raw.blue << std::endl;
+	 * 			std::cout << "Clear: " << raw.clear << std::endl;
+	 * 			pros::delay(20);
+	 * 		}
+	 * }
+	 * \endcode
 	 */
 	virtual pros::c::optical_raw_s_t get_raw();
 
 	/**
 	 * Get the most recent gesture data from the sensor
 	 *
 	 * Gestures will be cleared after 500mS
-	 * 0 = no gesture
-	 * 1 = up (towards cable)
-	 * 2 = down
-	 * 3 = right
+	 * 
+	 * 0 = no gesture,
+	 * 1 = up (towards cable),
+	 * 2 = down,
+	 * 3 = right,
 	 * 4 = left
 	 *
 	 * This function uses the following values of errno when an error state is
@@ -336,6 +353,7 @@ class Optical : public Device {
 	 * 			pros::delay(20);
 	 * 		}
 	 * }
+	 * \endcode
 	 */
 	virtual std::int32_t enable_gesture();
 

src/devices/vdml_distance.cpp

@@ -22,6 +22,10 @@ std::int32_t Distance::get() {
 	return pros::c::distance_get(_port);
 }
 
+std::int32_t Distance::get_distance() {
+	return get();
+}
+
 std::vector<Distance> Distance::get_all_devices() {
 	std::vector<Device> matching_devices {Device::get_all_devices(DeviceType::distance)};
 	std::vector<Distance> return_vector;