[OCaml] High Intensity Training Online
docs apply STE100 fixes to prose comments
Documentation-only STE100 compliance pass over doc comments and prose code comments in the core library. Split semicolon prose into separate sentences, rewrite passive voice to active where the agent is known, resolve ambiguous pronouns, shorten over-long sentences, and remove Latinate padding. No behavior change.
Changed files
lib/core/evidence.mli
@@ -54,9 +54,9 @@
54
54
end
55
55
56
56
(** A prescribed workout as observed through its whole life. A workout may be
57
Removed:
edited before or after it ends. The log records what happened, so
58
Removed:
[add_stimulus], [replace_stimulus], and [record_at] deliberately accept an
59
Removed:
ended workout as well as an in-progress workout. *)
57
Added:
edited before or after it ends. The log records what happened. For this
58
Added:
reason, [add_stimulus], [replace_stimulus], and [record_at] deliberately
59
Added:
accept an ended workout as well as an in-progress workout. *)
60
60
module Workout : sig
61
61
type t
62
62
type shape = As_single | As_pair
@@ -90,10 +90,11 @@
90
90
91
91
val replace_stimulus : t -> slot:int -> Stimulus.t -> t
92
92
(** Records the stimulus into a named prescription slot, replacing whatever
93
Removed:
filled that slot before. A correction, not extra work: it targets the slot
94
Removed:
and never appends volume. The stimulus must conform to that slot's
95
Removed:
prescription. Raises [Invalid (No_such_slot _)] for an unknown slot, and
96
Removed:
[Invalid] for a stimulus the slot does not call for. *)
93
Added:
filled that slot before. This is a correction, not extra work. The
94
Added:
operation targets the slot and never appends volume. The stimulus must
95
Added:
conform to that slot's prescription. Raises [Invalid (No_such_slot _)] for
96
Added:
an unknown slot, and [Invalid] for a stimulus the slot does not call for.
97
Added:
*)
97
98
98
99
val finish : t -> ended_at:Recovery.timestamp -> t
99
100
(** Sets [ended_at] once. Later calls retain the first value. *)
@@ -116,10 +117,10 @@
116
117
117
118
val record_at : t -> slot:int -> Stimulus.t -> t
118
119
(** Append a stimulus at a named slot, preserving any prior fill of that slot.
119
Removed:
The faithful-replay primitive: it reconstructs {!performed} verbatim,
120
Removed:
including recorded extra volume, without the slot-clearing that
121
Removed:
{!replace_stimulus} performs. Validates the stimulus against the slot and
122
Removed:
raises [Invalid] as {!replace_stimulus} does. *)
120
Added:
This is the faithful-replay primitive. It reconstructs {!performed}
121
Added:
verbatim, including recorded extra volume, without the slot-clearing that
122
Added:
{!replace_stimulus} performs. This operation validates the stimulus
123
Added:
against the slot and raises [Invalid] as {!replace_stimulus} does. *)
123
124
124
125
val filled_slots : t -> int
125
126
(** How many distinct prescription slots have a record. Never exceeds the
lib/core/exercise.ml
@@ -97,9 +97,9 @@
97
97
let id t = t.id
98
98
let name t = t.name
99
99
100
Removed:
(* The muscle a set is prescribed to train, counted toward the per-muscle
101
Removed:
ceiling. Catalog entries always carry a non-empty muscle list: an isolation
102
Removed:
names one muscle, a compound names its primary first. *)
100
Added:
(* The muscle the exercise trains, which counts toward the per-muscle ceiling.
101
Added:
Catalog entries always carry a non-empty muscle list: an isolation names one
102
Added:
muscle, a compound names its primary first. *)
103
103
let primary_muscle t = List.hd t.muscles
104
104
let equal a b = key_equal a.key b.key
105
105
let pp ppf t = Format.pp_print_string ppf t.name
lib/core/exercise.mli
@@ -95,9 +95,11 @@
95
95
val pp : Format.formatter -> t -> unit
96
96
97
97
val may_pre_exhaust : isolation:t -> compound:t -> bool
98
Removed:
(** Whether the isolation and the compound may pair. True only when the
99
Removed:
isolation targets one muscle, the compound trains that muscle, and the
100
Removed:
compound trains two or more muscles. *)
98
Added:
(** Whether the isolation and the compound may pair. True only when all three
99
Added:
conditions hold:
100
Added:
- the isolation targets one muscle,
101
Added:
- the compound trains that muscle, and
102
Added:
- the compound trains two or more muscles. *)
101
103
102
104
val may_substitute : original:t -> candidate:t -> bool
103
105
(** Whether [candidate] is author-approved for [original]. *)
lib/core/feedback.ml
@@ -1,4 +1,4 @@
1
Removed:
(* Subjective self-reports, kept apart from Evidence: what the trainee said,
1
Added:
(* Subjective self-reports, apart from Evidence: what the trainee said,
2
2
not what the body did. *)
3
3
4
4
type level = Worse_than_usual | As_usual | Better_than_usual
lib/core/feedback.mli
@@ -1,6 +1,6 @@
1
1
(** Subjective self-reports at a point in time: what the trainee said, not what
2
Removed:
the body did. HD1 grounds two, and gauges recovery by time and by effect
3
Removed:
rather than by a wider battery of wellness proxies. *)
2
Added:
the body did. HD1 grounds two of them. HD1 gauges recovery by time and by
3
Added:
effect, not by a wider battery of wellness proxies. *)
4
4
5
5
type level =
6
6
| Worse_than_usual
@@ -9,9 +9,9 @@
9
9
(** A self-report relative to the trainee's usual baseline, not an
10
10
absolute score. HD1 frames both signals this way — Difficulty is "the
11
11
weights feel much heavier than usual". Three values resist the false
12
Removed:
precision of a finer scale, in the spirit of HD1's refusal of spurious
13
Removed:
measurement gradations. [Worse_than_usual] is the concerning direction
14
Removed:
for both signals. *)
12
Added:
precision of a finer scale, and match HD1's refusal of a finer
13
Added:
measurement scale. [Worse_than_usual] is the concerning direction for
14
Added:
both signals. *)
15
15
16
16
val pp_level : Format.formatter -> level -> unit
17
17
@@ -19,12 +19,12 @@
19
19
| Motivation of level
20
20
| Difficulty of level
21
21
(** The only self-reports HD1 grounds. Motivation is HD1 chapter 6, and a
22
Removed:
halt in it is a recognized overtraining symptom ("with those who
23
Removed:
chronically overtrain, such a disinclination is easy to understand").
24
Removed:
Difficulty is HD1's "the weights feel much heavier than usual" — a
25
Removed:
depletion symptom. HD1 gauges recovery by time and by effect (a stall
26
Removed:
or decompensation), not by a wider battery of wellness proxies, so
27
Removed:
none are modeled. *)
22
Added:
halt in motivation is a recognized overtraining symptom ("with those
23
Added:
who chronically overtrain, such a disinclination is easy to
24
Added:
understand"). Difficulty is HD1's "the weights feel much heavier than
25
Added:
usual" — a depletion symptom. HD1 gauges recovery by time and by
26
Added:
effect (a stall or decompensation), not by a wider battery of wellness
27
Added:
proxies. This module models none of the other proxies. *)
28
28
29
29
type t
30
30
type error = Duplicate_signal of signal
lib/core/prescription.ml
@@ -116,8 +116,8 @@
116
116
Format.fprintf ppf "%a receives %d sets, over the ceiling of %d"
117
117
Exercise.Muscle.pp muscle sets sets_per_muscle_ceiling
118
118
119
Removed:
(* Each delivery exercise counts one set toward its primary muscle;
120
Removed:
substitutes are alternatives, not added volume. Returns the first muscle
119
Added:
(* Each delivery exercise counts one set toward its primary muscle.
120
Added:
Substitutes are alternatives, not added volume. Returns the first muscle
121
121
over the ceiling, if any. *)
122
122
let over_ceiling stimuli =
123
123
let primaries =
lib/core/prescription.mli
@@ -75,7 +75,7 @@
75
75
(** Raises [Invalid Empty_workout] for an empty workout, and
76
76
[Invalid (Excess_sets_per_muscle _)] when a muscle would receive more than
77
77
{!sets_per_muscle_ceiling} sets. Each delivery exercise counts one set
78
Removed:
toward its primary muscle; substitutes do not add volume. *)
78
Added:
toward its primary muscle. Substitutes do not add volume. *)
79
79
80
80
val name : t -> string
81
81
val stimuli : t -> Stimulus.t list
lib/core/progress.ml
@@ -56,10 +56,10 @@
56
56
match (observations, last observations) with
57
57
| ([] | [ _ ]), _ | _, None -> raise (Invalid Insufficient_data)
58
58
| first :: _, Some latest -> (
59
Removed:
(* Once the window has passed without progress, separate a halt from a
60
Removed:
loss: strength below the reference is decompensation, strength holding
61
Removed:
at it is a stall. The reference is the peak reached (the last advance),
62
Removed:
or the first observation when the record never advanced. *)
59
Added:
(* After the window passes without progress, separate a halt from a loss.
60
Added:
Strength below the reference is decompensation. Strength that holds at
61
Added:
the reference is a stall. The reference is the peak reached (the last
62
Added:
advance), or the first observation when the record never advanced. *)
63
63
let effort = Evidence.Observation.effort in
64
64
let verdict ~reference =
65
65
if declines ~previous:(effort reference) ~current:(effort latest) then
@@ -108,8 +108,8 @@
108
108
109
109
type load_verdict = Hold | Increase of float * float | Too_heavy
110
110
111
Removed:
(* The trigger is absolute, so the window's ceiling never gates the verdict —
112
Removed:
only its floor does. *)
111
Added:
(* The trigger is absolute. The window ceiling never gates the verdict. Only
112
Added:
the window floor does. *)
113
113
let judge_load ~rep_range effort =
114
114
let reps = Effort.reps effort in
115
115
let min_reps, _ = Prescription.Rep_range.bounds rep_range in
@@ -207,17 +207,17 @@
207
207
beats ~previous:comparison.previous ~current:comparison.current)
208
208
209
209
(* How many distinct exercises in [workout] beat their most recent earlier
210
Removed:
observation in [log]. Progress is the Heavy Duty signal — an increase in reps
211
Removed:
or load — judged here, in the one module that judges, so a caller receives a
212
Removed:
count and never re-derives the rule. An exercise with no earlier observation
213
Removed:
does not count. *)
210
Added:
observation in [log]. Progress is the Heavy Duty signal: an increase in reps
211
Added:
or load. This module judges it, so a caller receives a count and never
212
Added:
re-derives the rule. An exercise with no earlier observation does not
213
Added:
count. *)
214
214
let workout_progress log workout = List.length (workout_changes log workout)
215
215
216
216
(* The most recent observation of [target]'s exercise strictly before [target]
217
Removed:
was performed, taken from [observations] (any order). The same baseline rule
218
Removed:
as [previous_effort], but over a bare observation series rather than a log,
219
Removed:
so imported evidence — which is not a native workout — can still be compared
220
Removed:
against what came before it. *)
217
Added:
was performed, taken from [observations] (any order). This applies the same
218
Added:
baseline rule as [previous_effort], but over a bare observation series rather
219
Added:
than a log. Imported evidence is not a native workout. A caller can still
220
Added:
compare it against the observations before it. *)
221
221
let previous_observation observations (target : Evidence.Observation.t) =
222
222
let exercise = Evidence.Observation.exercise target in
223
223
let performed = Evidence.Observation.performed_at target in
lib/core/progress.mli
@@ -5,9 +5,10 @@
5
5
| Stalled
6
6
| Decompensating
7
7
(** [Stalled] is a halt: progress has stopped but strength holds.
8
Removed:
[Decompensating] is worse: strength is being lost (HD1, "The Economics
9
Removed:
of Growth and Recovery": "before decompensating, i.e., lose strength
10
Removed:
and mass"). HD1 names both and applies the same corrective. *)
8
Added:
[Decompensating] is worse: the trainee loses strength (HD1, "The
9
Added:
Economics of Growth and Recovery": "before decompensating, i.e., lose
10
Added:
strength and mass"). HD1 names both and applies the same corrective.
11
Added:
*)
11
12
12
13
type error = Insufficient_data
13
14
@@ -33,7 +34,8 @@
33
34
val remedy : assessment -> remedy option
34
35
(** [Some] for [Stalled] and [Decompensating]. HD1 applies one corrective to a
35
36
halt and to decompensation alike ("when progress comes to a halt or you
36
Removed:
start decompensating ... you should decrease them"). It never adds work. *)
37
Added:
start decompensating ... you should decrease them"). The corrective never
38
Added:
adds work. *)
37
39
38
40
val pp_remedy : Format.formatter -> remedy -> unit
39
41
@@ -83,9 +85,9 @@
83
85
84
86
val workout_progress : Evidence.Log.t -> Evidence.Workout.t -> int
85
87
(** How many distinct exercises in the workout beat their most recent earlier
86
Removed:
observation in the log. Progress is more reps or load; one extra rep counts.
87
Removed:
An exercise with no earlier observation does not count, and the baseline is
88
Removed:
the latest observation strictly before the workout started, so correcting a
88
Added:
observation in the log. Progress is more reps or load. One extra rep counts.
89
Added:
An exercise with no earlier observation does not count. The baseline is the
90
Added:
latest observation strictly before the workout started, so correcting a
89
91
saved workout never compares an exercise against itself. *)
90
92
91
93
val previous_observation :
@@ -93,6 +95,6 @@
93
95
Evidence.Observation.t ->
94
96
Evidence.Observation.t option
95
97
(** The most recent observation of the target's exercise strictly before the
96
Removed:
target was performed, from the given series. The baseline rule of
97
Removed:
{!workout_comparisons}, over a bare observation list, so imported evidence
98
Removed:
can be compared against what came before it. *)
98
Added:
target was performed, from the given series. This applies the baseline rule
99
Added:
of {!workout_comparisons} over a bare observation list. A caller can then
100
Added:
compare imported evidence against the observations before it. *)
lib/core/routines.ml
@@ -1,7 +1,8 @@
1
Removed:
(* Authored routines. HD1 supplies one, the Ideal Routine, reproduced here
2
Removed:
exactly: its supersets as pre-exhaust pairs, its own "or" lists as permitted
3
Removed:
substitutes, the 6-10 band on every exercise. This is doctrine content, kept
4
Removed:
apart from the plan types in [Prescription] that it is built from. *)
1
Added:
(* Authored routines. HD1 supplies one, the Ideal Routine, which this module
2
Added:
reproduces exactly: its supersets as pre-exhaust pairs, its own "or" lists as
3
Added:
permitted substitutes, the 6-10 band on every exercise. This is doctrine
4
Added:
content. It stays apart from the plan types in [Prescription] that build
5
Added:
it. *)
5
6
6
7
open Prescription
7
8
open Exercise