Documentation #43

agent-q1 · 2020-07-20T12:35:49Z

Docs

This Pull Request adds some documentation for the Implementation of HPA* we have in Terasology.

…nto Documentation

RatMoleRat

There's a few repeated things that should be changed, mostly with formatting (changing capitalization and/or deleting extra lines). I left several more specific comments on specific lines.

src/main/java/org/terasology/navgraph/BaseRegion.java

RatMoleRat · 2020-07-25T19:21:45Z

src/main/java/org/terasology/navgraph/BaseRegion.java

    protected BaseRegion(int id) {
        this.id = id;
        map = new BitMap();
    }

+    /**
+     * Marks a point in the region as walkable by characters
+     * @param x x co-ordinate of the point with respect to region's top-left corner


Same here (and elsewhere, I won't mark them all) as for the "id id" comment above

RatMoleRat · 2020-07-25T19:25:45Z

src/main/java/org/terasology/navgraph/BaseRegion.java

    public Set<N> getNeighborRegions() {
        return neighborRegions;
    }

+    /**
+     *
+     * @return The id of the base region along with the number of neighbouring regions


Start the statement after @return with a lowercase letter

RatMoleRat · 2020-07-25T19:26:11Z

src/main/java/org/terasology/navgraph/BitMap.java

@@ -20,12 +20,17 @@

 /**
 * @author synopia
+ * Representation of a any region or floor


Is the "a" here a typo?

RatMoleRat · 2020-07-25T19:27:54Z

src/main/java/org/terasology/navgraph/BitMap.java

+    /**
+     * Creates a new Bitmap
+     */
+


Get rid of this extra line

RatMoleRat · 2020-07-25T19:50:31Z

src/main/java/org/terasology/navgraph/WalkableBlock.java

@@ -18,7 +18,8 @@
 import org.terasology.math.geom.Vector3i;

 /**
- * @author synopia
+ * @author synopia Represents a Block through which characters can walk through. They are blocks which have atleast 2


New line here, too, and space between the two parts of "at least".

RatMoleRat · 2020-07-25T19:50:51Z

src/main/java/org/terasology/navgraph/WalkableBlock.java

@@ -18,7 +18,8 @@
 import org.terasology.math.geom.Vector3i;

 /**
- * @author synopia
+ * @author synopia Represents a Block through which characters can walk through. They are blocks which have atleast 2
+ *         penetrable blocks above them and are themselves not penetrable


Not sure why this is indented

That happens as a part of automatic line formatting. I think I'll let it stay

RatMoleRat · 2020-07-25T19:51:19Z

src/main/java/org/terasology/navgraph/WalkableBlockFinder.java

+     * Finds Walkable Blocks in  NavGraphChunk. Blocks are considered Walkable only if there is enough space above them
+     * to allow for walking
+     *
+     * @param map


What is "map" here?

Added small description

RatMoleRat · 2020-07-25T19:51:28Z

src/main/java/org/terasology/navgraph/WalkableBlockFinder.java

@@ -29,6 +29,13 @@ public WalkableBlockFinder(WorldProvider world) {
        this.world = world;
    }

+    /**
+     * Finds Walkable Blocks in  NavGraphChunk. Blocks are considered Walkable only if there is enough space above them


RatMoleRat · 2020-07-25T19:55:44Z

src/main/java/org/terasology/navgraph/WalkableBlockFinder.java

@@ -72,6 +79,16 @@ private void findNeighbors(NavGraphChunk map) {
        }
    }

+    /**
+     * Connects Cells to adjacent cells if possible


Could be worded better for more clarity - something like "Connects [each cell? a cell?] to adjacent cells if possible."

skaldarnar

Please excuse me obstructing this PR 🙈 If left a bunch of questions that may help to provide JavaDoc that helps somebody who has no clue what all of this is about (like me 😅 ).
I hope to get the message across that the answers to these basic questions are what I'm looking in the documentation of a class.

src/main/java/org/terasology/navgraph/BaseRegion.java

skaldarnar · 2020-08-04T18:20:01Z

src/main/java/org/terasology/navgraph/BaseRegion.java

    protected BaseRegion(int id) {
        this.id = id;
        map = new BitMap();
    }

+    /**
+     * Marks a point in the region as walkable by characters
+     * @param x the x co-ordinate of the point with respect to region's top-left corner


what is the "top-left corner" of a region?

what defines the sizes of a region?

what exactly does "walkable" mean, e.g., is this about solid ground characters can walk on, or about passable blocks characters can move through (might be swimming, crouching, ...)?

So they way it was created, walkable blocks are all those blocks on which a (1x1x1) cube character can walk. A non penetrable block underneath and some air blocks above. (Currently set to 2 IIRC). The don't include any other features such as swimming/ crouching.

skaldarnar · 2020-08-04T18:21:55Z

src/main/java/org/terasology/navgraph/BaseRegion.java

+    /**
+     *
+     * @return the id of the base region along with the number of neighbouring regions
+     */
    @Override
    public String toString() {
        return id + "\nrc = " + neighborRegions.size();


If not strictly necessary I'd think that the string representation could simply be something like "NavRegion(<id>, <size>)", avoiding line breaks.

src/main/java/org/terasology/navgraph/BaseRegion.java

src/main/java/org/terasology/navgraph/BitMap.java

agent-q1 added 2 commits July 1, 2020 12:43

Added Basic Documentation

4db1d9f

Merge branch 'develop' of https://github.com/Terasology/Pathfinding i…

5ecdfe0

…nto Documentation

RatMoleRat suggested changes Jul 25, 2020

View reviewed changes

docs: Added better formatting

b02215d

skaldarnar reviewed Aug 4, 2020

View reviewed changes

docs: Added clearer documentation

358e548

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation #43

Documentation #43

agent-q1 commented Jul 20, 2020

RatMoleRat left a comment

RatMoleRat Jul 25, 2020

RatMoleRat Jul 25, 2020

RatMoleRat Jul 25, 2020

RatMoleRat Jul 25, 2020

RatMoleRat Jul 25, 2020

RatMoleRat Jul 25, 2020

agent-q1 Jul 31, 2020

RatMoleRat Jul 25, 2020

agent-q1 Jul 31, 2020

RatMoleRat Jul 25, 2020

RatMoleRat Jul 25, 2020

skaldarnar left a comment

skaldarnar Aug 4, 2020

agent-q1 Aug 14, 2020

skaldarnar Aug 4, 2020

Documentation #43

Are you sure you want to change the base?

Documentation #43

Conversation

agent-q1 commented Jul 20, 2020

Docs

RatMoleRat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

skaldarnar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment