Added some javadocs #3217

Adrijaned · 2018-01-10T19:22:33Z

Contains

Adds or edits a bunch of javadocs for a GCI task.

How to test

Since there are no code related changes, there is no testing required/possible.

GooeyHub · 2018-01-10T19:22:33Z

Can one of the admins please verify this patch?

vampcat · 2018-01-10T23:30:32Z

engine/src/main/java/org/terasology/utilities/subscribables/AbstractGeneralSubscribable.java

-/**
- * {@inheritDoc}
- */
+


It's great that you decided to remove these redundant javadocs.

However, note that every method now has 2 newlines (in this case, 20 and 21) perceding it. We usually like 1 newline. Can you please remove the extra newline for all the javadocs you deleted?

vampcat · 2018-01-10T23:31:44Z

engine/src/main/java/org/terasology/world/chunks/Chunk.java

@@ -19,6 +19,7 @@
 import org.terasology.module.sandbox.API;

 /**
+ * This interface bundles together all the methods chunk contains.


The name of the interface is Chunk, so obviously it will bundle the methods of chunk - doesn't really help the reader. I would like to see a more concrete description of this (explain what a chunk is).

vampcat · 2018-01-10T23:33:01Z

engine/src/main/java/org/terasology/world/chunks/CoreChunk.java

@@ -37,56 +37,211 @@
 */
 @API
 public interface CoreChunk {
+    /**
+     * @return Position of the chunk in blocks


"position of the chunk in blocks"
This is not entirely clear. What do you mean? Do you mean it returns the local position of the chunk within a block, or blocks is the unit (like 3 blocks away from origin) ?

vampcat · 2018-01-10T23:36:55Z

engine/src/main/java/org/terasology/world/generation/BaseFacetedWorldGenerator.java

@@ -20,6 +20,9 @@
 import org.terasology.world.generator.WorldConfigurator;
 import org.terasology.world.generator.WorldGenerator;

+/**
+ * The most common implementation of {@link WorldGenerator} based on the idea of Facets


"The most common implementation"
The word common seems strange in this context. Common in what sense? Most commonly implemented (as in multiple people implement it, and most people implement this) or most commonly used implementation (implemented by one person, and used by most users) or what? Can you replace it with something else?
A basic implementation or something.

vampcat · 2018-01-10T23:42:44Z

engine/src/main/java/org/terasology/world/generation/BaseFacetedWorldGenerator.java

@@ -83,6 +89,10 @@ public World getWorld() {
        return world;
    }

+    /**
+     * Returns current {@link WorldBuilder} or creates new if none exists


The way your sentence is structured, it will

Return existing one if it exists

Or create a new one (and not return anything).
Rephrase it. The job of a javadocs writer is not just to convert getWorldBuilder to Returns world builder.

For reference, this is how I would personally write it:
Returns the current WorldBuilder used by this WorldGenerator. If no WorldBuilder has been initialized so far, a new one is created and then returned.
Kinda verbose, but much more clear in meaning.

Also, don't leave the @return blank.
@return The WorldBuilder used by this WorldGenerator or something.
I realize there is some duplication, but it's inevitable.

vampcat · 2018-01-10T23:47:54Z

engine/src/main/java/org/terasology/world/generator/WorldGenerator.java

+    /**
+     * Sets the seed to use for creating of the world made by this world generator.
+     * <p>
+     * NOTE: this is a String value. The long value used in the most common implementation of this interface


Instead of writing "in the most common implementation" link to the implementation that you're talking about.

vampcat

Thansk for the changes.

pollend · 2018-01-13T21:08:38Z

engine/src/main/java/org/terasology/world/chunks/Chunk.java

@@ -19,6 +19,9 @@
 import org.terasology.module.sandbox.API;

 /**
+ * Chunks are the smallest logical units of the worlds.
+ *
+ * Each chunk is 32x32x64 in dimensions, and is the default unit passed to world generator during world generation.


and is the default unit passed to world generator during world generation. I'm not sure what this means exactly. I think you are talking about chunks as if they were a unit. The basic concept of a chunk is to allow the world to be partitioned into manageable blocks. maybe talk about a chunk in those terms rather than as a cubic unit.

I think the size of a chunk is defined in ChunkConstants. Probably it is better to add a reference to ChunkConstants instead of duplicating the values in the documentation here.

oniatus

One more improvement then this should be good to go :)

oniatus · 2018-01-20T18:26:17Z

engine/src/main/java/org/terasology/world/chunks/Chunk.java

@@ -19,6 +19,9 @@
 import org.terasology.module.sandbox.API;

 /**
+ * Chunks are the smallest logical units of the worlds.
+ *
+ * Each chunk is 32x32x64 in dimensions, and is the default unit passed to world generator during world generation.


I think the size of a chunk is defined in ChunkConstants. Probably it is better to add a reference to ChunkConstants instead of duplicating the values in the documentation here.

emanuele3d · 2018-02-03T16:10:36Z

@oniatus can you have a look at the latest changes and see if they are satisfactory? It'd be good to get this small PR out of the way.

oniatus · 2018-02-03T16:23:43Z

Looks okay. We may update the javadoc once we have sectors because then chunks have an impact on the entity-system too, at least as far as I know :) For now this is okay.

emanuele3d · 2018-02-03T23:09:15Z

Merged! Thanks @Adrijaned! Another PR bites the dust!

Added javadocs

b69d62c

vampcat suggested changes Jan 10, 2018

View reviewed changes

Fixed some javadocs

725353a

vampcat approved these changes Jan 11, 2018

View reviewed changes

pollend reviewed Jan 13, 2018

View reviewed changes

oniatus suggested changes Jan 20, 2018

View reviewed changes

Adrijaned and others added 3 commits January 21, 2018 12:20

Some javadocs

a904ad2

fixed a small javadoc issue

72a52cb

Improved javadoc of the Chunk interface.

8efedcb

oniatus approved these changes Feb 3, 2018

View reviewed changes

emanuele3d merged commit 3ff63da into MovingBlocks:develop Feb 3, 2018

Cervator added this to the Alpha 9 milestone Feb 4, 2018

Cervator added the Category: Doc Requests, Issues and Changes targeting javadoc and module documentation label Feb 4, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added some javadocs #3217

Added some javadocs #3217

Adrijaned commented Jan 10, 2018

GooeyHub commented Jan 10, 2018

vampcat Jan 10, 2018

vampcat Jan 10, 2018

vampcat Jan 10, 2018

vampcat Jan 10, 2018

vampcat Jan 10, 2018

vampcat Jan 10, 2018

vampcat Jan 10, 2018

vampcat left a comment

pollend Jan 13, 2018

oniatus Jan 20, 2018

oniatus left a comment

oniatus Jan 20, 2018

emanuele3d commented Feb 3, 2018

oniatus commented Feb 3, 2018

emanuele3d commented Feb 3, 2018

Added some javadocs #3217

Added some javadocs #3217

Conversation

Adrijaned commented Jan 10, 2018

Contains

How to test

GooeyHub commented Jan 10, 2018

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

vampcat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oniatus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

emanuele3d commented Feb 3, 2018

oniatus commented Feb 3, 2018

emanuele3d commented Feb 3, 2018