javadoc updates

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/Main.java

@@ -34,7 +34,7 @@
  * <li>-ppmot -i input -o output</li>
  * </ul>
  *
- * @author Adrián González Sieira <adrian.gonzalez@usc.es>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  */
 public class Main {
 

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/distance/JOctreeDistanceMap.java

@@ -24,15 +24,15 @@
  * Represents a map distance based in a {@link JOctree} structure,
  * allowing queries as "nearest obstacle to".
  *
- * @author Adrián González Sieira <adrian.gonzalez@usc.es>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  */
 public class JOctreeDistanceMap extends NativeObject{
 
 	/**
 	 * Initializes this object with the pointer to the native object
 	 * of the library.
-	 * 
-	 * @param pointer
+	 *
+	 * @param pointer pointer to the native object (JNI global reference)
 	 */
 	private JOctreeDistanceMap(long pointer) {
 		super(pointer);
@@ -46,30 +46,31 @@ private JOctreeDistanceMap(long pointer) {
 	/**
 	 * Retrieves the distance to the nearest obstacle, if there is one
 	 * in the radius of the "maxDistance" of this distance max.
-	 * @param x
-	 * @param y
-	 * @param z
-	 * @return
+	 *
+	 * @param x query point, coordinate X
+	 * @param y query point, coordinate Y
+	 * @param z query point, coordinate Z
+	 * @return distance to the nearest obstacle
 	 */
 	public native double getDistance(double x, double y, double z);
 
 	/**
 	 * Retrieves the distance to the nearest obstacle given the
 	 * {@link JOctreeKey} of a node as origin.
 	 * 
-	 * @param key
-	 * @return
+	 * @param key {@link JOctreeKey} of the cell to query
+	 * @return distance to the nearest obstacle
 	 */
 	public native double getDistance(JOctreeKey key);
 
 	/**
 	 * Retrieves the distance and location of the nearest obstacle to the given
 	 * 3D point. If this method does not find any obstacle in the maximum
 	 * distance (specified at the creation of the distance map), this method returns null.
-	 * @param x
-	 * @param y
-	 * @param z
-	 * @return <distance, location> of the nearest obstacle, null if no obstacle found at the maximum distance of this map
+	 * @param x query point, coordinate X
+	 * @param y query point, coordinate Y
+	 * @param z query point, coordinate Z
+	 * @return {@literal <distance, location>} of the nearest obstacle, null if no obstacle found at the maximum distance of this map
 	 */
 	public native Obstacle getDistanceAndClosestObstacle(double x, double y, double z);
 

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/iterators/LeafBBXIterator.java

@@ -21,18 +21,17 @@
 import es.usc.citius.lab.motionplanner.core.spatial.Point3D;
 
 /**
- * Implements an iterator for the {@link JOctreeNode} of a
- * given {@link JOctree}, which  
+ * Implements an iterator for navigating the {@link JOctreeNode} of a {@link JOctree}, which only traverses the leaves in a given bounding box.
  *
- * @author Adrián González Sieira <adrian.gonzalez@usc.es>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  */
 public class LeafBBXIterator extends OctreeIterator{
 
 	/**
 	 * Default constructor for this class, that takes the native pointer to the iterator and
 	 * the native pointer to the end point of the created iterator.
 	 * 
-	 * @param pointer
+	 * @param pointer pointer to the native object (JNI global reference)
 	 */
 	private LeafBBXIterator(long pointer) {
 		super(pointer);

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/iterators/OctreeIterator.java

@@ -29,7 +29,7 @@
  * current element using the methods {@link #key()}, {@link #coordinate()}, {@link #depth()},
  * {@link #node()}, {@link #x()} and {@link #y()}.
  *
- * @author Adrián González Sieira <adrian.gonzalez@usc.es>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  */
 public abstract class OctreeIterator extends NativeObject implements Iterator<JOctreeKey>{
 

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/module/AdjacencyMapBuilder.java

@@ -30,7 +30,7 @@
  * 		<li>Obtain a new {@link JOctree} from a PPM image</li>
  * </ul>
  * 
- * @author Adrián González Sieira <adrian.gonzalez@usc.es>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  */
 public class AdjacencyMapBuilder extends Module{
 

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/module/JOCtreeBuilder.java

@@ -35,7 +35,7 @@
  * 		<li>Obtain a new {@link JOctree} from a PPM image</li>
  * </ul>
  * 
- * @author Adrián González Sieira <adrian.gonzalez@usc.es>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  */
 public class JOCtreeBuilder extends Module{
 
@@ -63,7 +63,7 @@ public void execute(CommandLine args) {
      * @param resolution min size of the cells
      * @param sizeX max. size of the X dimension of the map
      * @param maxDepthCell number of levels which a cell is allowed to compact
-     * @return
+     * @return new {@link JOctree} with the information of the PPM file
      */
     public static JOctree octreeFromPPM(String input, float resolution, float sizeX, int maxDepthCell){
         //read the ppm file 

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/module/Module.java

@@ -27,7 +27,7 @@
  * Definition of an executable module for the application. The
  * program will find all the subclasses of Module and re
  *
- * @author Adrián González Sieira <adrian.gonzalez@usc.es>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  */
 public abstract class Module {
 
@@ -55,13 +55,13 @@ public static Options getGenericOptions() {
 	 * Executes the functions of the module based on the {@link CommandLine} parsed
 	 * arguments.
 	 * 
-	 * @param args
+	 * @param args parsed {@link CommandLine} arguments
 	 */
 	public abstract void execute(CommandLine args);
 
 	/**
 	 * Register all available modules in the application.
-	 * @return
+	 * @return map with the string/class modules found in the source code
 	 */
     private static Map<String, Class<?>> registerModules(){
         Map<String, Class<?>> modulesMap = new HashMap<String, Class<?>>();

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/octree/JOctree.java

@@ -50,7 +50,7 @@ public class JOctree extends NativeObject{
 	 * Initializes the JOctree with a pointer to the native OcTree object of
 	 * the Octomap library. Used by native methods.
 	 * 
-	 * @param pointer pointer to the native OcTree object.
+	 * @param pointer pointer to the native OcTree object (JNI global reference)
 	 */
 	private JOctree(long pointer) {
 		super(pointer);
@@ -73,21 +73,21 @@ protected void finalize() throws Throwable {
 	/**
 	 * Retrieves the position of the cell at a current 
 	 * location.
-	 * 
-	 * @param x
-	 * @param y
-	 * @param z
+	 *
+	 * @param x query point, coordinate X
+	 * @param y query point, coordinate Y
+	 * @param z query point, coordinate Z
 	 * @return key of the node at the given position
 	 */
 	public native JOctreeKey coordToKey(float x, float y, float z);
 
 	/**
 	 * Retrieves the position of the cell at a current 
 	 * location, at a given depth.
-	 * 
-	 * @param x
-	 * @param y
-	 * @param z
+	 *
+	 * @param x query point, coordinate X
+	 * @param y query point, coordinate Y
+	 * @param z query point, coordinate Z
 	 * @param depth level to search (depth=0 means search in the full octree)
 	 * @return key of the node at the given position and depth
 	 */
@@ -117,7 +117,7 @@ protected void finalize() throws Throwable {
 	 * 
 	 * @param point coordinate to query the key of the node at that position
 	 * @param depth of the {@link JOctreeKey} in the octree
-	 * @return
+	 * @return {@link JOctreeKey} of cell which contains the given point at a given depth
 	 */
 	public native JOctreeKey coordToKey(Point3D point, int depth);
 
@@ -172,10 +172,10 @@ public JOctreeNode search(JOctreeKey key){
 	/**
 	 * Retrieves a node of the {@link JOctree} in a given position of the 3D space and a depth level
 	 * of the octree.
-	 * 
-	 * @param x 
-	 * @param y
-	 * @param z
+	 *
+	 * @param x query point, coordinate X
+	 * @param y query point, coordinate Y
+	 * @param z query point, coordinate Z
 	 * @param depth level to search (depth=0 means search in the full octree)
 	 * @return node of the octree, if found, null otherwhise
 	 */
@@ -185,9 +185,9 @@ public JOctreeNode search(JOctreeKey key){
 	 * Calls the method {@link #search(float, float, float, int)} with the default value of 
 	 * depth=0. Default values in argument methods are not supported by Java, so this method overload
 	 * tries to emulate the call with the default value depth = 0;
-	 * @param x
-	 * @param y
-	 * @param z
+	 * @param x query point, coordinate X
+	 * @param y query point, coordinate Y
+	 * @param z query point, coordinate Z
 	 * @return node of the octree, if found, null otherwise
 	 */
 	public JOctreeNode search(float x, float y, float z){
@@ -211,11 +211,11 @@ public JOctreeNode search(float x, float y, float z){
 	/**
 	 * Updates the occupancy information of a {@link JOctreeNode}, retrieving the node 
 	 * instance affected.
-	 * 
-	 * @param x
-	 * @param y
-	 * @param z
-	 * @param occupied
+	 *
+	 * @param x query point, coordinate X
+	 * @param y query point, coordinate Y
+	 * @param z query point, coordinate Z
+	 * @param occupied occupancy value to set
 	 * @return {@link JOctreeNode} affected
 	 */
 	public native JOctreeNode updateNode(float x, float y, float z, boolean occupied);

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/octree/JOctreeKey.java

@@ -23,7 +23,7 @@
  * used to store the nodes in the data structure. This is not a native
  * object wrapper since it has not associated functions.
  * 
- * @author Adrián González Sieira <adrian.gonzalez@usc.es>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  */
 public class JOctreeKey implements Serializable{
 
@@ -34,10 +34,10 @@ public class JOctreeKey implements Serializable{
 	/**
 	 * Default constructor that initializes the 3D coordinates
 	 * of the key.
-	 * 
-	 * @param x
-	 * @param y
-	 * @param z
+	 *
+	 * @param x key, coordinate X
+	 * @param y key, coordinate Y
+	 * @param z key, coordinate Z
 	 */
 	public JOctreeKey(int x, int y, int z) {
 		this.x = x;
@@ -77,15 +77,24 @@ public boolean equals(Object obj) {
 	public String toString() {
 		return "{" + x + ", " + y + ", " + z + "}";
 	}
-
+
+	/**
+	 * @return key, coordinate X
+	 */
 	public int getX() {
 		return x;
 	}
-
+
+	/**
+	 * @return key, coordinate Y
+	 */
 	public int getY() {
 		return y;
 	}
-
+
+	/**
+	 * @return key, coordinate Z
+	 */
 	public int getZ() {
 		return z;
 	}

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/octree/JOctreeNode.java

@@ -28,7 +28,7 @@
  * Since this is a native object, it extends to {@link NativeObject}
  * to store the pointer properly.
  *
- * @author Adrián González Sieira <adrian.gonzalez@usc.es>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  */
 public class JOctreeNode extends NativeObject{
 

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/util/AdjacencyMap.java

@@ -43,7 +43,7 @@
  * important to recalculate the adjacency of the cells if the geometry of the map changes
  * (new cells added, or the size of the cells changes).
  *
- * @author Adrián González Sieira <<a href="mailto:adrian.gonzalez@usc.es">adrian.gonzalez@usc.es</a>>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  * @since 09/03/2016
  */
 public class AdjacencyMap implements Serializable{
@@ -138,23 +138,31 @@ public static AdjacencyMap createJava(JOctree octree){
     /**
      * This fills the structures of the adjacency map using full-native
      * implementation method for efficiency.
+     *
+     * @param octree octree to calculate the adjacency map from
      */
     private native void initializeJNI(JOctree octree);
 
     /**
      * Retrieves the adjacencies for a current key.
      *
      * @param key instance of {@link JOctreeKey}
-     * @return
+     * @return list of adjacent {@link JOctreeKey} of a given one
      */
     public List<JOctreeKey> adjacency(JOctreeKey key){
         return adjacencies.get(key);
     }
 
+    /**
+     * @return map with the keys and adjacencies contained in the map
+     */
     public Map<JOctreeKey, List<JOctreeKey>> getAdjacencies(){
         return adjacencies;
     }
 
+    /**
+     * @return map with the information of the octree cells (key, size and coordinate)
+     */
     public Map<JOctreeKey, Pair<Float, Point3D>> getNodesInfo() {
         return nodesInfo;
     }

joctomap-core/src/main/java/es/usc/citius/lab/joctomap/util/CollisionChecker2D.java

@@ -24,7 +24,7 @@
  * This class implements a collision checker which uses native methods to determine
  * the collision in a 2D octree using 2D shapes (circular and rectangular).
  *
- * @author Adrián González Sieira <adrian.gonzalez@usc.es>
+ * @author Adrián González Sieira {@literal <adrian.gonzalez@usc.es>}
  */
 public class CollisionChecker2D {