Fix missing documentation for many clock faces:

* Move from .c to .h as needed for consistency.
* When missing from both, copy from pull request or wiki.
* When missing entirely, infer functionality from source code.

movement/watch_faces/settings/finetune_face.c

@@ -20,21 +20,6 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
- *
- * FineTune face allows to align watch with sub-second precision in 25/250ms accuracy.
- * Counts time since previous finetune, and allows to calculate & apply ppm correction for nanosec.
- *
- * Main screen - adjust delay (light/alarm)
- * Long mode press - show hours since previous finetune
- * Long mode press - show calculated ppm correction. You can apply it with long light, or just reset finetune timer with long alarm.
- *
- * Finetune will apply crystal aging correction on every finetune save (as aging is calculated since "last finetune" timestamp) - but you should worry
- * about aging only on second/third years of watch calibration (if you are really looking at less than 10 seconds per year of error).
- *
- * Warning, do not use at the first second of a month, as you might stay at the same month and it will surprise you.
- * Just wait 1 second...We are not fully replicating RTC timer behavior when RTC is off.
- * Simulating months and years is... too much complexity.
- *
  */
 
 #include <stdlib.h>

movement/watch_faces/settings/finetune_face.h

@@ -25,6 +25,34 @@
 #ifndef FINETUNE_FACE_H_
 #define FINETUNE_FACE_H_
 
+/*
+ * FINETUNE face
+ *
+ * FineTune face allows to align watch with sub-second precision in 25/250ms
+ * accuracy. Counts time since previous finetune, and allows to calculate &
+ * apply ppm correction for nanosec.
+ *
+ * Best used in conjunction with the NANOSEC face.
+ *
+ * Main screen - adjust delay (light/alarm)
+ * Long MODE press - show hours since previous finetune
+ * Long MODE press - show calculated ppm correction.
+ *  You can apply it with long LIGHT, or just reset finetune timer with long ALARM.
+ *
+ * Finetune will apply crystal aging correction on every finetune save
+ * (as aging is calculated since "last finetune" timestamp); but you should
+ * worry about aging only on second/third years of watch calibration (if you
+ * are really looking at less than 10 seconds per year of error).
+ *
+ * Warning, do not use at the first second of a month, as you might stay at
+ * the same month and it will surprise you. Just wait 1 second...We are not
+ * fully replicating RTC timer behavior when RTC is off.
+ * Simulating months and years is... too much complexity.
+ *
+ * For full usage instructions, please refer to the wiki:
+ *  https://www.sensorwatch.net/docs/watchfaces/nanosec/
+ */
+
 #include "movement.h"
 
 typedef struct {

movement/watch_faces/settings/nanosec_face.c

@@ -22,33 +22,6 @@
  * SOFTWARE.
  */
 
-/*
- * The goal of nanosec face is dramatic improvement of SensorWatch accuracy.
- * Minimum goal is <60 seconds of error per year. Full success is if we can reach <15 seconds per year (<0.47ppm error).
- *
- * It implements temperature correction using tempco from datasheet (and allows to adjust these)
- * and allows to introduce offset fix. Therefore requires temperature sensor board.
- *
- * Most users will need to apply profile 3 ("default") or 2("conservative datasheet"), and tune first parameter -
- * static offset (as it's different for every crystal sample).
- *
- * Frequency correction is dithered over 31 correction intervals (31x10 minutes or ~5 hours), to allow <0.1ppm correction resolution.
- * 1ppm is 0.0864 sec per day.
- * 0.1ppm is 0.00864 sec per day.
- *
- * To stay under 1ppm error you would need calibration of your specific instance of quartz crystal after some "burn-in" (ideally 1 year).
- *
- * Should improve TOTP experience.
- *
- * Default funing fork tempco: -0.034 ppm/°C², centered around 25°C
- * We add optional cubic coefficient, which was measured in practice on my sample.
- *
- * Cadence (CD) - how many minutes between corrections. Default 10 minutes.
- * Every minute might be too much. Every hour - slightly less power consumption but also less precision.
- *
- * Can compensate crystal aging (ppm/year) - but you really should be worrying about it on second/third years of watch calibration. *
- */
-
 #include <stdlib.h>
 #include <string.h>
 #include <math.h>

movement/watch_faces/settings/nanosec_face.h

@@ -25,6 +25,47 @@
 #ifndef NANOSEC_FACE_H_
 #define NANOSEC_FACE_H_
 
+/*
+ * NANOSEC face
+ *
+ * The goal of nanosec face is dramatic improvement of SensorWatch accuracy.
+ * Minimum goal is <60 seconds of error per year. Full success is if we can
+ * reach <15 seconds per year (<0.47ppm error).
+ *
+ * Best used in conjunction with the FINETUNE face.
+ *
+ * It implements temperature correction using tempco from datasheet (and
+ * allows to adjust these) and allows to introduce offset fix. Therefore
+ * requires temperature sensor board.
+ *
+ * Most users will need to apply profile 3 ("default") or 2 ("conservative
+ * datasheet"), and tune first parameter "static offset" (as it's different
+ * for every crystal sample).
+ *
+ * Frequency correction is dithered over 31 correction intervals (31x10
+ * minutes or ~5 hours), to allow <0.1ppm correction resolution.
+ *  * 1ppm is 0.0864 sec per day.
+ *  * 0.1ppm is 0.00864 sec per day.
+ *
+ * To stay under 1ppm error you would need calibration of your specific
+ * instance of quartz crystal after some "burn-in" (ideally 1 year).
+ *
+ * Should improve TOTP experience.
+ *
+ * Default funing fork tempco: -0.034 ppm/°C², centered around 25°C
+ * We add optional cubic coefficient, which was measured in practice on my sample.
+ *
+ * Cadence (CD) - how many minutes between corrections. Default 10 minutes.
+ * Every minute might be too much. Every hour - slightly less power
+ * consumption but also less precision.
+ *
+ * Can compensate crystal aging (ppm/year) - but you really should be worrying
+ * about it on second/third years of watch calibration.
+ *
+ * For full usage instructions, please refer to the wiki:
+ *  https://www.sensorwatch.net/docs/watchfaces/nanosec/
+ */
+
 #include "movement.h"
 
 #define nanosec_profile_count 5

movement/watch_faces/settings/preferences_face.h

@@ -25,6 +25,57 @@
 #ifndef PREFERENCES_FACE_H_
 #define PREFERENCES_FACE_H_
 
+/*
+ * PREFERENCES face
+ *
+ * The Preferences watch face allows you to configure various options on your
+ * Sensor Watch. Like all other screens, you advance the field you’re setting
+ * with the Light button, and advance its value with the Alarm button. The
+ * Preferences watch face labels each setting with a two-letter code on the
+ * top row; the following list describes each setting and their options:
+ *
+ *  CL - Clock mode.
+ *      This setting allows you to select a 12-or 24-hour clock display. All
+ *      watch faces that support displaying the time will respect this setting;
+ *      for example, both Simple Clock, World Clock and Sunrise/Sunset will
+ *      display the time in 24 hour format if the 24 hour clock is selected here.
+ *
+ *  BT - Button tone.
+ *      This setting is only relevant if you installed the buzzer connector,
+ *      and it toggles the beep when changing modes. If Y, the buzzer will
+ *      sound a tone when Mode is pressed. Change to N to make the Mode
+ *      button silent.
+ *
+ *  TO - Timeout.
+ *      Sets the time until screens that time out (like Settings and Time Set)
+ *      snap back to the first screen. 60 seconds is a good default for the
+ *      stock firmware, but if you choose a custom firmware with faces that
+ *      you’d like to keep on screen for longer, you can set that here.
+ *
+ *  LE - Low Energy mode.
+ *      Sets the time until the watch enters its low energy sleep mode.
+ *      Options range from 1 hour to 7 days, or Never. The more often Sensor
+ *      Watch goes to sleep, the longer its battery will last — but you will
+ *      lose the seconds indicator while it is asleep. This setting allows
+ *      you to make a tradeoff between the device’s responsiveness and its
+ *      longevity.
+ *
+ *  LT - Light.
+ *      This setting has three screens.
+ *      The first lets you choose how long the LED should stay lit when the
+ *       LIGHT button is pressed. Options are 1 second, 3 seconds and 5
+ *       seconds, or “No LED” to disable the LED entirely.
+ *      The second screen, titled “blu” or “grn”, sets the intensity of the
+ *       blue or green LED depending on the target Sensor Board hardware.
+ *       Values range from 0 (off) to 15 (full intensity).
+ *      The third screen, “red”, sets the intensity of the red LED, again
+ *       from 0 to 15.
+ *      On the last two screens, the LED remains on so that you can see the
+ *      effect of mixing the two LED colors. On the Special Edition boards,
+ *      you’ll have red, blue and a variety of shades of pink and purple to
+ *      experiment with!
+ */
+
 #include "movement.h"
 
 void preferences_face_setup(movement_settings_t *settings, uint8_t watch_face_index, void ** context_ptr);

movement/watch_faces/settings/set_time_face.h

@@ -25,6 +25,23 @@
 #ifndef SET_TIME_FACE_H_
 #define SET_TIME_FACE_H_
 
+/*
+ * SET TIME face
+ *
+ * The default method for adjusting Sensor Watch time.
+ *
+ * The Time Set watch face allows you to set the time on Sensor Watch. Use
+ * the LIGHT button to advance through the field you are setting, and the
+ * ALARM button to change the value in that field. The fields are, in order:
+ * Hour, Minute, Second, Year, Month, Day and Time Zone.
+ *
+ * For features like World Clock and Sunrise/Sunset to work correctly, you
+ * must set the time to your local time, and the time zone to your local time
+ * zone. This allows Sensor Watch to correctly offset the time. This also
+ * means that when daylight savings time starts or ends, you must update
+ * both the time and the time zone on this screen.
+ */
+
 #include "movement.h"
 
 void set_time_face_setup(movement_settings_t *settings, uint8_t watch_face_index, void ** context_ptr);

movement/watch_faces/settings/set_time_hackwatch_face.c

@@ -21,21 +21,6 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
- * 
- * 
- * 
- * This is an extended version of set_time face which allow setting seconds precisely.
- * To achieve that - press and hold alarm button few seconds before 00 and release exaclty as reference clock turns 00.
- * All settings can go up, or down (long alarm press).
- * 
- * The challenge is that SensorWatch display is delayed 0.5 seconds vs hardware RTC clock. It is caused by interrupts being generated by raising
- * edge of counter. It means there is no way to precisely trigger at 0.5s, as events at different frequencies slightly mismatch. 
- * This watch face achieves this approximately by triggering at 15th out of 32Hz events.
- * 
- * If you are <30 seconds when setting seconds - you will stay in the same minute. Otherwise - you will go to next minute. 
- * 
- * Note that changing anything will slightly delay subseconds counter. This is why this face sets seconds last 
- * to achiveve best precision. Still, best possible precision is achieved with finetune face. 
  */
 
 #include <stdlib.h>

movement/watch_faces/settings/set_time_hackwatch_face.h

@@ -25,6 +25,29 @@
 #ifndef SET_TIME_HACKWATCH_FACE_H_
 #define SET_TIME_HACKWATCH_FACE_H_
 
+/*
+ * SET TIME HACKWATCH
+ *
+ * This is an extended version of set_time face which allow setting seconds
+ * precisely. To achieve that - press and hold alarm button few seconds before
+ * 00 and release exaclty as reference clock turns 00.
+ *
+ * All settings can go up, or down (long alarm press).
+ * 
+ * The challenge is that SensorWatch display is delayed 0.5 seconds vs hardware
+ * RTC clock. It is caused by interrupts being generated by raising edge of
+ * counter. It means there is no way to precisely trigger at 0.5s, as events
+ * at different frequencies slightly mismatch. This watch face achieves this
+ * approximately by triggering at 15th out of 32Hz events.
+ * 
+ * If you are <30 seconds when setting seconds - you will stay in the same
+ * minute. Otherwise - you will go to next minute. 
+ * 
+ * Note that changing anything will slightly delay subseconds counter. This
+ * is why this face sets seconds last to achiveve best precision. Still,
+ * best possible precision is achieved with finetune face. 
+ */
+
 #include "movement.h"
 
 void set_time_hackwatch_face_setup(movement_settings_t *settings, uint8_t watch_face_index, void ** context_ptr);