Commits

bergsoe committed 4f0cef9

API doc.

Comments (0)

Files changed (15)

src/PaplConstraint.mli

     rejects} a value.
 
     If [c] is a constraint and [x] is a value, then [x] is accepted if [accept c
-    x] and rejected if [reject c x]. [accept c x] is equivalent to [not (reject
-    c x)].
+    x] is true and rejected if [reject c x] is true. The call [accept c x] is
+    equivalent to [not (reject c x)].
 *)
 
-(** {2 Constraints} *)
-
-(** {3 Types} *)
+(** {2 Types} *)
 
 type 'a t
 (** The type of a constraint on values of type ['a]. *)
 
-(** {3 Operations} *)
+(** {2 Operations} *)
 
 val accept : 'a t -> 'a -> bool
 (** [accept c x] is true if and only if [c] accepts [x]. *)
 val reject : 'a t -> 'a -> bool
 (** [reject c x] is true if and only if [c] rejects [x]. *)
 
-(** {3 Constructors} *)
+(** {2 Constructors} *)
 
 val make_accept : ('a -> bool) -> 'a t
 (** The constraint [c = make_accept f] accepts [x] if and only if [f x] is
 val constrain_path : 'a t -> 'a list t
 (** A constraint for a path.
 
-    The path constraint [pc = constrain_path c] rejects a list [xs] if any of
-    the elements [x] of [xs] is rejected by [c].
+    The constraint [c' = constrain_path c] rejects a list [xs] if any of the
+    elements [x] of [xs] is rejected by [c].
 *)

src/PaplDLTree.mli

 *)
 
 type 'a node
-  (** The type of a node of the tree.
+(** The type of a node of the tree.
 
-      The node stores a value of type ['a].
-  *)
+    The node stores a value of type ['a].
+*)
 
 val add_root : 'a -> 'a node
-  (** Add an element as the root of a new tree and return the new root
-      node.
-  *)
+(** Add an element as the root of a new tree and return the new root
+    node.
+*)
 
 val is_root : 'a node -> bool
+(** [is_root node] is [true] if [node] is a root node.
+*)
 
 val add : 'a node -> 'a -> 'a node
-  (** Add a new element as a child node of a node and return the new node.
+(** Add a new element as a child node of a node and return the new node.
 
-      The node [n' = add n q] is a new child node of [n] and stores the element
-      [q].
-  *)
+    The node [n' = add n q] is a new child node of [n] and stores the element
+    [q].
+*)
 
 val get : 'a node -> 'a
-  (** The element value stored in a node. *)
+(** The element value stored in a node. *)
 
 val parent : 'a node -> 'a node option
-  (** The parent of a node or [None] if the node is a root node. *)
+(** The parent of a node or [None] if the node is a root node. *)
 
 val children : 'a node -> 'a node BatEnum.t
 (** The children of a node. *)
 
 val filter_nodes_to_root : 
   ('a node -> bool) -> 'a node -> 'a node list
+(** [filter_nodes_to_root f node] is the list of nodes from [node] up to and
+    including the root node for which [f] returns [true].
+*)
 
 val fold_nodes_to_root :
   ('acc -> 'a node -> 'acc) ->
   'acc
 
 val node_path_to_root : 'a node -> 'a node list
-  (** [node_path_to_root node] is the list of nodes from [node] up to and
-      including its root.
+(** [node_path_to_root node] is the list of nodes from [node] up to and
+    including its root.
 
-      If [node] is a root node then the result is the single-element list
-      [[node]].
-  *)
+    If [node] is a root node then the result is the single-element list
+    [[node]].
+*)
 
 val path_to_root : 'a node -> 'a list
-  (** [path_to_root node] is the list of elements values on the path from
-      node up to and including its root.
+(** [path_to_root node] is the list of elements values on the path from
+    node up to and including its root.
 
-      If [node] is a root node then the result is [get node].
+    If [node] is a root node then the result is [get node].
 
-      [path_to_root node] is equivalent to
-      [List.map get (node_path_to_root node)].
-  *)
+    [path_to_root node] is equivalent to
+    [List.map get (node_path_to_root node)].
+*)
 
 val constr : 'a PaplConstraint.t -> 'a node PaplConstraint.t
 (** Convert a constraint for a value to a constraint for a node.
    to an end point [b].
 *)
 
+(** {2 Types} *)
+
 type 'a t = 'a * 'a
+(** The type of an edge. *)

src/PaplEdgeConstraint.mli

    certain properties of the edge are satisfied.
 *)
 
-(** {2 Edge constraints} *)
-
-(** {3 Types} *)
+(** {2 Types} *)
 
 type 'a t = 'a PaplEdge.t PaplConstraint.t
 (** An edge constraint.
 *)
 
-(** {3 Constructors} *)
+(** {2 Constructors} *)
 
 val constrain_both : 'a PaplConstraint.t -> 'a t
 (** A constraint on both elements of a pair.
   'a PaplInterpolate.t ->
   'a PaplMetric.threshold_t ->
   'a t
+(** The edge constraint [ec = constrain_by_subdivision c ip (metric, eps)]
+    splits an edge [(q_a, q_b)] into a sequence of intermediary configurations
+    [q(1), ..., q(N)] for which [metric qi q(i+1) <= eps] for all [i] and checks
+    each configuration by [c].
+
+    See {! PaplIncrEdgeConstraint.constrain_by_subdivision} for more details on
+    the operation and assumptions of the function.
+*)
+
+(** {2 Conversions} *)
 
 val constrain_path : 'a t -> 'a list PaplConstraint.t
 (**
     equal to the length of [edge] measured by [metric].
 *)
 
+(** {2 Metrics} *)
+
 module Metric : sig
   val to_option : 'a t -> 'a PaplMetric.t -> 'a PaplMetric.option_t
 (** Convert a metric to a metric option by applying a constraint to the

src/PaplIncrConstraint.mli

 (** {2 Types} *)
 
 type t
-(** An incremental constraint for values of type ['a]. *)
+(** An incremental constraint. *)
 
 type 'a create_t = 'a -> t
 (** Constructor of an incremental constraint for a value of type ['a].

src/PaplIncrEdgeConstraint.mli

 
     The constraint does not check the start and end points of the input edge.
 
-    The cost of the constraint equals current length of the subsegments.
+    The cost of the constraint equals the current length of the subsegments.
 *)
 
 val constrain_path : 'a create_t -> 'a list -> PaplIncrConstraint.t

src/PaplMetric.mli

    - reflexivity
    - triangle inequality
 
-   but many algorithms on metric implementations are correct even if none of
-   those properties are satisfied.
-
-   Consult the documentation for each algorithm to know the requirements for the
-   metric.
+   but metric implementations aren't required to satisfy these laws. It is the
+   responsibility of each algorithm that uses a metric to specify the laws that
+   the metric must satisfy.
 *)
 
 (** {2 Types} *)
 *)
 
 val interpolate : 'a PaplInterpolate.t -> 'a pair_t PaplInterpolate.t
+(** The function [interpolate ip] interpolates pairs by interpolating each
+    coordinate using [ip].
+*)
 
 module Int : sig
   type t = int pair_t
     A path must have length at least 2.
 *)
 
+(** {2 Types} *)
+
 type 'a t = 'a list
+(** The type of a path. *)
+
+(** {2 Operations} *)
 
 val fold_adjacent : ('a -> 'a -> 'acc -> 'acc) -> 'a t -> 'acc -> 'acc
+(** [fold_adjacent f \[q(1), q(2), ..., q(N)\] acc] is equivalent to
+    [f q(N-1) q(N) ... (f q(2) q(3) (f q(1) q(2) acc))].
+*)

src/PaplPlanner.mli

 
 (** {2 Types} *)
 
-(** The type of a planner.
-
+(*
     A call [planner stop (from, to)] of a planner [planner] searches for a path
     connecting a start region [from] to a goal region [end]. The planner
     regularly calls [stop] to decide if the search should continue. The planner
 
 type 'a region_pair_t = 'a region_t pair_t
 
-(* path *)
+exception Path_not_found of string
+
+(** {3 Path planner types} *)
 
 type ('target, 'q) t =
     PaplStopCriteria.t -> 'target -> 'q list
 
 type 'a sampler_t = ('a region_pair_t, 'a) t
 
-(* trajectory *)
+(** {3 Trajectory planner types} *)
 
 type ('target, 'q) trajectory_t =
     PaplStopCriteria.t -> 'target -> 'q PaplTrajectory.t
 type 'a sampler_trajectory_t =
     ('a region_pair_t, 'a) trajectory_t
 
-exception Path_not_found of string
+(** {2 Miscellaneous} *)
 
 val to_option : ('target, 'q) t -> ('target, 'q) option_t
 
-val to_trajectory :
-  ('a list -> 'b PaplTrajectory.t) ->
-  ('target, 'a) t ->
-  ('target, 'b) trajectory_t
-(** Path planner to trajectory planner conversion.
-   
-    [to_trajectory convert planner] calls [convert] on the path of [planner] to
-    convert the result to a trajectory type.
-*)
-
 val fail : string -> 'a
 (** [fail msg] raises [Path_not_found msg]. *)
 
+(** {3 Path planner operations} *)
+
 val bind_target : ('b -> 'a) -> ('a, 'q) t -> ('b, 'q) t
 
 val map_path : ('q -> 'r) -> ('a, 'q) t -> ('a, 'r) t
    then [sp] fails too.
 *)
 
+(** {3 Trajectory planner operations} *)
+
 module Trajectory : sig
+  val to_trajectory :
+    ('a list -> 'b PaplTrajectory.t) ->
+    ('target, 'a) t ->
+    ('target, 'b) trajectory_t
+  (** Path planner to trajectory planner conversion.
+
+      [to_trajectory convert planner] calls [convert] on the path of [planner] to
+      convert the result to a trajectory type.
+  *)
+
   val of_metric :
     ?t0:float ->
     'a PaplInterpolate.t ->
     'a PaplMetric.t ->
     ('target, 'a) t ->
     ('target, 'a) trajectory_t
-(** Path planner to trajectory planner conversion.
-*)
-
+  (** Path planner to trajectory planner conversion.
+  *)
 end
 
+(** {3 Path planner module types} *)
+
 module type BIDIR = sig
   type q_t
   type a_t

src/PaplSampler.mli

 (** Sampling of values
 
-    A sampler is a stream of values of some type.
+    A sampler is a stream of values of some type. Samplers are imperative data
+    structures. Samplers are used throughout the library in the implementation
+    of sampling based planning algorithms.
 
-    A sampler ['a t] is a type synonym for the enumeration type {! 'a BatEnum.t}
+    A sampler ['a t] is a type synonym for the enumeration type ['a BatEnum.t]
     of the Batteries Included library. The library defines a number of useful
     functions for manipulating enumerations, such as maps and folds, and
     functions for constructing enumerations for different types of sequence
-    data. For example:
-
-    - {! PaplRandom} constructs enumerations of random numbers.
-
-    - {! BatList} converts between lists and enumerations.
-
-    A sampler is an imperative structure. Use {! BatLazyList} or similar if your
-    algorithm requires a purely functional stream.
+    data (see for example [BatList]).
 *)
 
 type 'a pair_t = 'a * 'a
+type rng_t = PaplRandom.rng_t
 
 (** {2 Types} *)
 
 
 (** {2 Random sampling} *)
 
-type rng_t = PaplRandom.rng_t
-
 val distribute_by_weight :
   ?rng:rng_t ->
   (float * 'a) BatEnum.t ->

src/PaplTrajectory.mli

   float option
 (** [find_discontinuity traj dt (metric, eps)] traverses [traj] in steps of [dt]
     and returns [Some t] if a [t] is found for which [metric (get traj t) (get
-    traj (t +. dt)) > eps]. If no such [t] is found the [None] is returned.
+    traj (t +. dt)) > eps]. If no such [t] is found then [None] is returned.
 *)
 
 module Tuple2 : sig

src/PaplTransform.mli

     (** The rotation angle. *)
 
   val in_range : float -> (float * float) -> bool
+    (** [in_range x (a, b)] is true if the angle [x] is on the shortest route
+        from the angle [a] to the angle [b].
+    *)
 
   module Sampler : sig
     val uniform : ?rng:rng_t -> (float * float) -> t PaplSampler.t
   include SE with type vec = SO3.vec and type rot = SO3.t
 
   val to_array : t -> float array
+  (** Convert a transformation to 12 element array of floats.
+
+      The layout of the array is
+
+      [[| r11; r12; r13; px;
+          r21; r22; r23; py;
+          r31; r32; r33; pz |]]
+
+      where the [r] is the rotation matrix representation of the orientation
+      and [(px, py, pz)] is the translation vector.
+  *)
 end
 *)
 
 type 'a node
-  (** The type of a node of the tree.
+(** The type of a node of the tree.
 
-      The node stores a value of type ['a].
-  *)
+    The node stores a value of type ['a].
+*)
 
 val add_root : 'a -> 'a node
-  (** Add an element as the root of a new tree and return the new root
-      node.
-  *)
+(** Add an element as the root of a new tree and return the new root
+    node.
+*)
 
 val add : 'a node -> 'a -> 'a node
-  (** Add a new element as a child node of a node and return the new node.
+(** Add a new element as a child node of a node and return the new node.
 
-      The node [n' = add n q] is a new child node of [n] and stores the element
-      [q].
-  *)
+    The node [n' = add n q] is a new child node of [n] and stores the element
+    [q].
+*)
 
 val get : 'a node -> 'a
-  (** The element value stored in a node. *)
+(** The element value stored in a node. *)
 
 val parent : 'a node -> 'a node option
-  (** The parent of a node or [None] if the node is a root node. *)
+(** The parent of a node or [None] if the node is a root node. *)
 
 val node_path_to_root : 'a node -> 'a node list
-  (** [node_path_to_root node] is the list of nodes from [node] up to and
-      including its root.
+(** [node_path_to_root node] is the list of nodes from [node] up to and
+    including its root.
 
-      If [node] is a root node then the result is the single-element list
-      [[node]].
-  *)
+    If [node] is a root node then the result is the single-element list
+    [[node]].
+*)
 
 val path_to_root : 'a node -> 'a list
-  (** [path_to_root node] is the list of elements values on the path from
-      node up to and including its root.
+(** [path_to_root node] is the list of elements values on the path from
+    node up to and including its root.
 
-      If [node] is a root node then the result is [get node].
+    If [node] is a root node then the result is [get node].
 
-      [path_to_root node] is equivalent to
-      [List.map get (node_path_to_root node)].
-  *)
+    [path_to_root node] is equivalent to
+    [List.map get (node_path_to_root node)].
+*)
 
 val constr : 'a PaplConstraint.t -> 'a node PaplConstraint.t
+(** The node constraint [nc = constr c] applies the constraint [c] to the value
+    in a node.
+*)
 
 val edge_constr : 'a PaplEdgeConstraint.t -> 'a node PaplEdgeConstraint.t
+(** The node edge constraint [ec = edge_constr c] applies the edge constraint
+    [c] to the values extracted from a pair of nodes.
+*)

src/PaplVector.mli

 (** {2 Miscellaneous} *)
 
   val map : (float -> float) -> t -> t
+(** Map a function onto the elements of a vector. *)
 
   val map2 : (float -> float -> float) -> t -> t -> t
 
   include ALL with type t = float * float
 
   type triangle_t = t * t * t
+  (** The type of a triangle. *)
+
   type triangle_geom_t = triangle_t array
+  (** The type of a soup of triangles. *)
 end
 
 (** {2 3D vectors} *)
   include ALL with type t = float * float * float
 
   type triangle_t = t * t * t
+  (** The type of a triangle. *)
+
   type triangle_geom_t = triangle_t array
+  (** The type of a soup of triangles. *)
 
   val cross : t -> t -> t
+  (** The cross product of a pair of vectors. *)
 end
 
 (** 4-tuples as vectors. *)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.