Commits

bergsoe committed b12a566

API doc.

  • Participants
  • Parent commits c3e3ea6

Comments (0)

Files changed (2)

File src/PaplTime.ml

   let time (qc, ec) = (Constraint.time qc, EdgeConstraint.time ec)
 
   let constrain_by_subdivision qt_constr qt_interpolate dt =
-    PaplPlannerConstraint.constrain_by_subdivision
-      qt_constr qt_interpolate (Metric.time, dt)
+    (qt_constr, EdgeConstraint.constrain_by_subdivision
+       qt_constr qt_interpolate dt)
 end

File src/PaplTime.mli

 (** A time configuration. *)
 
 type direction_t = Forward | Backward
+(** The direction of a search.
+
+    The value of this flag signifies whether a search goes forward in time
+    (towards greater time values) or backwards in time (towards smaller time
+    values).
+*)
 
 type range_t = float * float
 (** A time range.
 (** {2 Operations} *)
 
 val q : 'a t -> 'a
+(** The configuration part of a time configuration. *)
 
 val time : 'a t -> float
+(** The time value of a time configuration. *)
 
 val map_q : ('a -> 'b) -> 'a t -> 'b t
+(** Map a function onto the configuration part of a time configuration
+    and keep the time unchanged.
+*)
 
 val map_time : (float -> float) -> 'a t -> 'a t
+(** Map a function onto the time part of a time configuration
+    and keep the configuration unchanged.
+*)
 
 val get_range : ('a t * 'a t) -> range_t
+(** The time values of a pair of time configurations.
+*)
 
 (** {2 Planning spaces}
 *)
     'a t PaplInterpolate.t ->
     float ->
     'a t PaplEdgeConstraint.t
+(** Subdividing edge constraint for time configurations.
+
+    [constrain_by_subdivision constr interpolate dt] splits an edge into steps
+    in time of length (at most) [dt] using [interpolate] and verifies the
+    configurations by [constr].
+
+    See {! PaplEdgeConstraint.constrain_by_subdivision} for details.
+*)
 
   val q : 'a PaplEdgeConstraint.t -> 'a t PaplEdgeConstraint.t
+(** A constraint on the configuration part of a time configuration.
+
+    [q ec] accepts an edge [(qta, qtb)] if [ec] accepts the edge [(qta.q,
+    qtb.q)].
+*)
+
   val time : float PaplEdgeConstraint.t -> 'a t PaplEdgeConstraint.t
+(** A constraint on the time part of a time configuration.
+
+    [q ec] accepts an edge [(qta, qtb)] if [ec] accepts the edge [(qta.time,
+    qtb.time)].
+*)
 
+  (** Constrained metrics *)
   module Metric : sig
 
     val order_pair : 'a t PaplMetric.t -> 'a t PaplMetric.option_t pair_t
 *)
 module PlannerConstraint : sig
   val q : 'a PaplPlannerConstraint.t -> 'a t PaplPlannerConstraint.t
+(** Planner constraint on the configuration part of a time configuration.
+*)
 
   val time : float PaplPlannerConstraint.t -> 'a t PaplPlannerConstraint.t
+(** Planner constraint on the time part of a time configuration.
+*)
 
   val constrain_by_subdivision :
     'a t PaplConstraint.t ->
     'a t PaplInterpolate.t ->
     float ->
     'a t PaplPlannerConstraint.t
+(** Subdividing constraint for time configurations.
+
+    See {! EdgeConstraint.constrain_by_subdivision} and {!
+    PaplEdgeConstraint.constrain_by_subdivision} for details.
+*)
 end
 
 (**
 *)
 
   val within_time : 'a PaplMetric.t -> 'a t -> 'a t PaplConstraint.t
+(** Time distance constraint.
+
+    The constraint [within_time dist_time qta] accepts configurations [qtb] for
+    which the distance between [qta.q] and [qtb.q] measured by [dist_time] is
+    less than or equal to the absolute distance between [qta.time] and
+    [qtb.time].
+*)
 
   val all_within_time :
     'a PaplMetric.t -> 'a t list -> 'a t PaplConstraint.t
+(** Time distance constraint for a set of time configurations.
+
+    The constraint [all_within_time dist_time qts] accepts a configuration [qtb]
+    if [within_time dist_time qta] accepts [qtb] for all [qta] in [qts].
+*)
 
   val by_trajectory :
     ('a * 'b) PaplConstraint.t -> 'b PaplTrajectory.t -> 'a t PaplConstraint.t
 *)
 
   val get_uniform : ?rng:rng_t -> range_t -> 'a PaplSampler.t -> 'a t option
+(** A single random configuration sampled from a range and a sampler.
+
+    [get_uniform range sampler] returns a time configuration [{time; q}] where
+    [time] is sampled uniformly at random from [range] and [q] is a sample
+    extracted from [sampler].
+
+    If the range is empty an exception is raised.
+*)
 end
 
 (** {2 Paths} *)
 
 module Path : sig
   val of_metric : ?t0:float -> 'a list -> 'a PaplMetric.t -> 'a t list
+(** Time-stamp a list of configuration by a metric.
+
+    [qts = of_metric ~t0 qs dist] is a list of time-stamped configurations
+    containing the configurations of [qs]. The time stamp of the first
+    configuration [qt(0)] is [t0] (or [0.] if [t0] is omitted) and time stamp of
+    all other [qt(i)] is [qt(i-1).time +. dist_time qt(i-1) qt(i)].
+*)
 
   val scale_to : 'a t list -> float -> 'a t list
-  (* [scale_to path len] scales the time stamps of [path] such that the duration
-     of the path is equal to [len].
+  (** [scale_to path len] scales the time stamps of [path] such that the
+      duration of the path (the difference in time value between the first and
+      the last element) is equal to [len].
 
-     If the duration of [path] is zero, then [path] should be of length 2.
+      If the duration of [path] is zero, then [path] should be of length 2.
   *)
 end
 
 module Planner : sig
 
   val fail_if_unordered : 'a t * 'b t -> unit
+(** Fail with an error message if a pair of targets aren't in causal order.
+
+    [fail_if_unordered (qta, qtb)] fails if [qta.time > qtb.time].
+
+    The error is raised by calling {! PaplPlanner.fail}.
+*)
 
   val fail_if_too_far : 'a PaplMetric.t -> 'a t * 'a t -> unit
+(** Fail with an error message if the configurations of a pair of time values
+    are too far apart that the movement can executed in the allotted time.
+
+    [fail_if_too_far dist_time (qta, qtb)] fails if [dist_time qta.q qtb.q] is
+    greater than the absolute distance between [qta.time] and [qtb.time].
+
+    The error is raised by calling {! PaplPlanner.fail}.
+*)
 
   val fail_if_bad_point_target :
     'a t PaplConstraint.t ->