I love the detailed doc. I think it would be easier to read if there was more distinction between @param tags, e.g.
/// Plan multiple paths using a bidirectional RRT planner. This planner will
/// continue to explore and add new solution paths until terminated.
/// @param start_tree existing starting tree. This tree must contain at least
/// one node, but can contain multiple nodes as well. All nodes in @param
/// start_tree are assumed to be valid starting nodes, and if they are linked
/// together, they must have valid parent-child linkage.
/// @param goal_tree existing goal tree. This tree must contain at least one
/// node, but can contain multiple nodes as well. All nodes in @param
/// goal_tree are assumed to be valid goal nodes, and if they are linked
/// together, they must have valid parent-child linkage.
/// @param state_sampling_fn function to sample a new state.
/// @param nearest_neighbor_fn function to compute the nearest neighbor index
/// in the provided tree given the provided sample. If a negative index
/// (showing that no valid nearest neighbor could be found) planning is
/// terminated.
/// @param forward_propagation_fn function to forward propagate states from
/// the provided state to the provided sample. The propagated states are
/// returned as a vector<pair<state, relative_index>> in which state is the
/// new propagated state and relative_index is a relative index used to
/// connect the new state to the correct parent state. This relative_index is
/// the index of the parent state, relative to the vector of propagated nodes.
/// A negative value means the nearest neighbor in the tree, zero means the
/// first propagated node, and so on. NOTE - the relative parent index *must*
/// be lower than the index in the list of prograted nodes i.e. the first node
/// must have a negative value, and so on. While complicated, this structure
/// allows @param forward_propagation_fn to return an entire subtree at once.
/// @param state_added_callback_fn callback function called once a state is
/// added to the tree, providing a mutable reference to the tree and the index
/// of the newly-added state. This can be used, for example, to update a
/// KD-tree used for nearest neighbors. You can leave this default-constructed
/// ({}) if you do not need it.
/// @param states_connected_fn function to check if the two provided states, one
/// from each tree, are connected, and a solution has been found.
/// @param goal_bridge_callback_fn callback function called once a solution
/// "goal bridge", that is a pair of nodes, one from each tree, has been
/// found. It provides a mutable reference to the start tree, the goal bridge
/// index in the start tree, a mutable reference to the goal tree, the goal
/// bridge index in the goal tree, and a bool flag that specifies which tree
/// is the active tree. If this flag is true, start_tree is the active tree.
/// You can leave this default-constructed ({}) if you do not need it.
/// @param tree_sampling_bias probability that the next sample should be from
/// the target tree, rather than from calling @param state_sampling_fn.
/// @param p_switch_tree probability at each iteration that the active tree
/// should be swapped.
/// @param termination_check_fn Returns true if planning has been
/// terminated. The provided int64_t values are the current size of the start
/// and goal tree, respectively. These may be useful for a size-limited
/// planning problem.
/// @param rng a PRNG for use in internal sampling and tree swaps.
/// @return pair<paths, statistics> where paths is a vector of solution paths
/// and statistics is a map<string, double> of useful statistics collected
/// while planning.
calderpg
commented
5 years ago
I love the detailed doc. I think it would be easier to read if there was more distinction between
@paramtags, e.g.