diff --git a/libs/color-sensor/_locales/color-sensor-jsdoc-strings.json b/libs/color-sensor/_locales/color-sensor-jsdoc-strings.json
index 6c637a94..bcd25d8f 100644
--- a/libs/color-sensor/_locales/color-sensor-jsdoc-strings.json
+++ b/libs/color-sensor/_locales/color-sensor-jsdoc-strings.json
@@ -1,10 +1,10 @@
 {
   "sensors.ColorSensor": "The color sensor is a digital sensor that can detect the color or intensity\nof light that enters the small window on the face of the sensor.",
-  "sensors.ColorSensor.ambientLight": "Get current ambient light value from the color sensor.",
+  "sensors.ColorSensor.ambientLight": "Measures the ambient light value from 0 (darkest) to 100 (brightest).",
   "sensors.ColorSensor.color": "Get the current color from the color sensor.",
   "sensors.ColorSensor.colorMode": "Gets the current color mode",
   "sensors.ColorSensor.onColorDetected": "Registers code to run when the given color is detected.",
   "sensors.ColorSensor.onColorDetected|param|color": "the color to detect, eg: ColorSensorColor.Blue",
   "sensors.ColorSensor.onColorDetected|param|handler": "the code to run when detected",
-  "sensors.ColorSensor.reflectedLight": "Get current reflected light value from the color sensor."
+  "sensors.ColorSensor.reflectedLight": "Measures the reflected light value from 0 (darkest) to 100 (brightest)."
 }
\ No newline at end of file
diff --git a/libs/color-sensor/color.ts b/libs/color-sensor/color.ts
index b03f717c..8f4b143c 100644
--- a/libs/color-sensor/color.ts
+++ b/libs/color-sensor/color.ts
@@ -104,8 +104,8 @@ namespace sensors {
         }
 
         /**
-         * Get current ambient light value from the color sensor.
-         * @param color the color sensor to query the request
+         * Measures the ambient light value from 0 (darkest) to 100 (brightest).
+         * @param color the color sensor port
          */
         //% help=sensors/color-sensor/ambient-light
         //% block="`icons.colorSensor` %color| ambient light"
@@ -120,8 +120,8 @@ namespace sensors {
         }
 
         /**
-         * Get current reflected light value from the color sensor.
-         * @param color the color sensor to query the request
+         * Measures the reflected light value from 0 (darkest) to 100 (brightest).
+         * @param color the color sensor port
          */
         //% help=sensors/color-sensor/reflected-light
         //% block="`icons.colorSensor` %color| reflected light"