From 43fc6e5e2a6b4f33c817d84f10d7c3b5f107a72d Mon Sep 17 00:00:00 2001
From: Anders Lau Olsen
Date: Fri, 13 Apr 2012 12:03:18 +0200
Subject: [PATCH] API doc and removal of Float.flip_interpolate.

src/PaplInterpolate.ml  1 
src/PaplInterpolate.mli  43 ++++++++++++++++++++++++++
2 files changed, 26 insertions(+), 18 deletions()
diff git a/src/PaplInterpolate.ml b/src/PaplInterpolate.ml
index e04bbef..2a89d02 100644
 a/src/PaplInterpolate.ml
+++ b/src/PaplInterpolate.ml
@@ 45,7 +45,6 @@ let intermediary_steps interpolate (metric, eps) start goal =
module Float = struct
let interpolate a b s = a +. (b . a) *. s
 let flip_interpolate s a b = interpolate a b s
end
module Int = struct
diff git a/src/PaplInterpolate.mli b/src/PaplInterpolate.mli
index 7cbcf37..86e39fa 100644
 a/src/PaplInterpolate.mli
+++ b/src/PaplInterpolate.mli
@@ 6,9 +6,9 @@
Planning spaces
A motion planner searches for a path in a planning space. The type of the
 planning space is generally user defined and depends on the robot and the
 planning problem. This library does not distinguish between configuration
 space and state space planning. A member of a planning space is called a {b
+ planning space is user defined and depends on the robot and the planning
+ problem. This library does not distinguish between configuration space and
+ state space planning. A member of a planning space is called a {b
configuration} regardless of the nature of the planning.
Planning spaces may support a number of operations discussed in modules such
@@ 23,16 +23,23 @@
type 'a t = 'a > 'a > float > 'a
(** Interpolation function for a planning space.
 An interpolation function [interpolate] returns a configuration [x =
 interpolate s a b] on the path connecting [a] to [b]. The interpolation
 parameter [s] must be in the range [\[0, 1\]].
+ An interpolation function [interpolate] called as [x = interpolate s a b]
+ returns a configuration [x] on the movement connecting [a] to [b]. The
+ interpolation parameter [s] must be in the range [\[0, 1\]].
*)
type 'a intermediary_t = 'a > 'a > 'a BatEnum.t
+(** Splitting of a movement into intermediary configurations.
+
+ A function [intermediary] called as [intermediary a b] returns a stream of
+ configurations on the movement from [a] to [b]. Algorithms that use such
+ functions generally expect [intermediary a b] not to include [a] and [b] in
+ the stream.
+*)
val intermediary_steps :
'a t > 'a PaplMetric.threshold_t > 'a intermediary_t
(** If [it = intermediary_steps ip (metric, eps)] then [it a b] are the
+(** If [im = intermediary_steps ip (metric, eps)] then [im a b] are the
intermediary steps of length [eps] connecting [a] to [b].
[a] and [b] are not explicitly included in the stream (but they can be if
@@ 43,27 +50,29 @@ val intermediary_steps :
(** Planning space for floats.
 Configurations are floats.

Floats are interpolated linearly.
*)
module Float : sig
val interpolate : float t
 val flip_interpolate : float > float > float > float
end
(** {2 Int planning space} *)
+(** Planning space for integers.
+
+ The integers are interpolated linearly as if they were floats and then
+ rounded to the nearest integer.
+*)
module Int : sig
val interpolate : int t
end
(** {2 Tuple planning spaces} *)
(** Planning space for tuples.
+(** Planning spaces for tuples.
 Tuples can contain values of seperate types. Each coordinate is interpolated
 using a seperate interpolation function.
+ Tuples coordinates can have separate types. Each coordinate is interpolated
+ with its own interpolation function.
*)
module Tuple2 : sig
@@ 82,9 +91,9 @@ end
Each coordinate is interpolated independently.
 The lists must be of the same length when interpolated.
+ Lists that are interpolated must have the same length; otherwise
+ [Invalid_argument] is raised.
*)

module List : sig
val interpolate : 'a t > 'a list t
end
@@ 97,9 +106,9 @@ end
Each coordinate is interpolated independently.
 Arrays being interpolated must be of the same length.
+ Arrays that are interpolated must have the same length; otherwise
+ [Invalid_argument] is raised.
*)

module Array : sig
val interpolate : 'a t > 'a array t
end

2.1.1