From 9393ea28c81e0bebb7dba1c25f695b16b6c9ba70 Mon Sep 17 00:00:00 2001
From: Anders Lau Olsen
Date: Sat, 14 Apr 2012 15:00:02 +0200
Subject: [PATCH] API doc.
---
src/PaplSBL.mli | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 75 insertions(+), 1 deletion(-)
diff --git a/src/PaplSBL.mli b/src/PaplSBL.mli
index d609fc0..4d91db0 100644
--- a/src/PaplSBL.mli
+++ b/src/PaplSBL.mli
@@ -11,21 +11,71 @@ type kind_t = Standard | NonTransfer
module type SETUP = sig
type t
+ (** Search trees. *)
+
type q_t
+ (** Configurations. *)
+
type value_t
+ (** The type of value stored in the nodes of the search tree.
+ *)
+
type node_t = value_t PaplDLTree.node
+ (** Tree nodes. *)
val expand : t -> node_t option
+ (** Search tree expansion function.
+
+ [expand s] adds zero or more new nodes to the tree. The method either
+ returns a single node [Some node] that other trees can connect to or
+ [None] if no such connection should be attempted.
+ *)
+
val connect : t -> q_t -> node_t option
+ (** Search tree connection function.
+
+ [connect s q] attempts to reach [q] from the search tree [s]. If [q] is
+ reached the function returns a node [Some node] of [s] such that the
+ movement from [node] to [q] is valid. Otherwise the functions return
+ [None].
+ *)
val remove_enum : t -> node_t BatEnum.t -> unit
+ (** Prepare a set of nodes for removal from the tree.
+
+ The function removes the nodes from any lookup tables or other internal
+ structures of the search tree state but does not actually detach the nodes
+ from their parents.
+ *)
+
val add : t -> node_t -> q_t -> PaplIncrConstraint.t -> node_t
+ (** Add a node to a search tree.
+
+ [node = add s parent q ec] is a new node of [s] with parent [parent] that
+ contains a configuration [q] and has a edge constraint [ec] with respect
+ to the movement to the parent.
+ *)
val get_q : value_t -> q_t
+ (** The configuration stored in a node value. *)
+
val get_ec : value_t -> PaplIncrConstraint.t ref
+ (** Reference to the edge constraint stored in a node value. *)
+
val make_constr : (q_t * q_t) -> PaplIncrConstraint.t
+ (** Construct an incremental edge constraint for the movement that connects a
+ pair of configurations.
+ *)
val kind : kind_t
+ (** The style of SBL search tree to construct.
+
+ [kind = Standard] means vanilla SBL.
+
+ [kind = NonTransfer] means that nodes of this search tree are never
+ transferred to other trees. If an edge turns out to be rejected, the
+ entire tree connected by the edge is simply erased.
+ *)
end
module type SETUP_PAIR = sig
@@ -55,12 +105,36 @@ module BruteForce : sig
include SETUP
val add_root : t -> q_t -> node_t
+ (** Add a root to a search tree.
+
+ The node [root = add_root s q] is a new root node of [s] containing the
+ value [q].
+ *)
+
val create : ?callback:(t -> unit) -> unit -> t
+ (** Construct a search tree.
+
+ The search tree [s = create ~callback ()] calls [callback] every time
+ [expand s] is being called.
+ *)
+
val create_point : q_t -> t
+ (** Construct a search tree for a point target.
+
+ The search tree [s = create_point q] contains a single root node with
+ the value [q].
+ *)
+
val create_region : q_t PaplPlanner.region_t -> t
+ (** Construct a search tree for a region target.
+
+ The search tree [s = create_region region] samples [region] every time
+ [expand s] is being called and inserts the resulting configurations as
+ root nodes of [s].
+ *)
val get_roots : t -> node_t BatEnum.t
- (** Enumeration of all nodes that have been added with {! add_root}. *)
+ (** Enumeration of all root nodes of the search tree. *)
end
module type SETUP_PAIR = sig
--
2.1.1