Merge remote-tracking branch 'origin/development' into dev/sharding-squash

Author: bogovicj

src/main/java/org/janelia/saalfeldlab/n5/N5Reader.java

@@ -284,6 +284,8 @@ <T> T getAttribute(
 	/**
 	 * Reads a {@link DataBlock}.
 	 *
+	 * @param <T>
+	 *            the DataBlock data type
 	 * @param pathName
 	 *            dataset path
 	 * @param datasetAttributes
@@ -305,6 +307,8 @@ <T> DataBlock<T> readBlock(
 	 * Implementations may optimize / batch read operations when possible, e.g.
 	 * in the case that the datasets are sharded.
 	 *
+	 * @param <T>
+	 *            the DataBlock data type
 	 * @param pathName
 	 *            dataset path
 	 * @param datasetAttributes

src/main/java/org/janelia/saalfeldlab/n5/N5Writer.java

@@ -220,7 +220,6 @@ default void createDataset(
 	 * @param dimensions the dataset dimensions
 	 * @param blockSize the block size
 	 * @param dataType the data type
-	 * @param blockCodecInfo the block codec
 	 * @param compression the compression
 	 */
 	default void createDataset(

src/main/java/org/janelia/saalfeldlab/n5/readdata/segment/SegmentedReadData.java

@@ -24,9 +24,14 @@ interface SegmentsAndData {
 	}
 
 	/**
-	 * Wrap {@code readData} and create one segment comprising the entire {@code
+	 * Wrap a {@link ReadData} and create one segment comprising the entire
+	 * {@code
 	 * readData}. The segment can be retrieved as the first (and only) element
 	 * of {@link SegmentedReadData#segments()}.
+	 * 
+	 * @param readData
+	 *            the ReadData to wrap
+	 * @return the SegmentedReadData
 	 */
 	static SegmentedReadData wrap(ReadData readData) {
 		return new DefaultSegmentedReadData(readData);
@@ -35,8 +40,15 @@ static SegmentedReadData wrap(ReadData readData) {
 	/**
 	 * Wrap {@code readData} and create segments at the given locations. The
 	 * order of segments in the returned {@link SegmentsAndData#segments()} list
-	 * matches the order of the given {@code locations} (while the {@link
-	 * #segments} in the {@link SegmentsAndData#data()} are ordered by offset).
+	 * matches the order of the given {@code locations} (while the
+	 * {@link #segments} in the {@link SegmentsAndData#data()} are ordered by
+	 * offset).
+	 * 
+	 * @param readData
+	 *            the ReadData to wrap
+	 * @param locations
+	 *            the ranges for segments
+	 * @return the SegmentsAndData
 	 */
 	static SegmentsAndData wrap(ReadData readData, Range... locations) {
 		return wrap(readData, Arrays.asList(locations));
@@ -45,8 +57,15 @@ static SegmentsAndData wrap(ReadData readData, Range... locations) {
 	/**
 	 * Wrap {@code readData} and create segments at the given locations. The
 	 * order of segments in the returned {@link SegmentsAndData#segments()} list
-	 * matches the order of the given {@code locations} (while the {@link
-	 * #segments} in the {@link SegmentsAndData#data()} are ordered by offset).
+	 * matches the order of the given {@code locations} (while the
+	 * {@link #segments} in the {@link SegmentsAndData#data()} are ordered by
+	 * offset).
+	 * 
+	 * @param readData
+	 *            the ReadData to wrap
+	 * @param locations
+	 *            the ranges for segments
+	 * @return the SegmentsAndData
 	 */
 	static SegmentsAndData wrap(ReadData readData, List<Range> locations) {
 		return DefaultSegmentedReadData.wrap(readData, locations);
@@ -57,41 +76,45 @@ static SegmentsAndData wrap(ReadData readData, List<Range> locations) {
 	 * given {@code readDatas}. The concatenation contains the segments of all
 	 * concatenated {@code readData}s with appropriately offset locations.
 	 * <p>
-	 * In particular, it is also possible to concatenate {@code SegmentedReadData}s
-	 * with (yet) unknown length. (This is useful for postponing compression of
-	 * DataBlocks until they are actually written.) In that case, segment locations
-	 * are only available after all lengths become known. This happens when
-	 * concatenation (or all its constituents) is {@link #materialize()
-	 * materialized} or {@link #writeTo(OutputStream) written}.
+	 * In particular, it is also possible to concatenate
+	 * {@code SegmentedReadData}s with (yet) unknown length. (This is useful for
+	 * postponing compression of DataBlocks until they are actually written.) In
+	 * that case, segment locations are only available after all lengths become
+	 * known. This happens when concatenation (or all its constituents) is
+	 * {@link #materialize() materialized} or {@link #writeTo(OutputStream)
+	 * written}.
+	 * 
+	 * @param readDatas
+	 *            a list of ReadDatra to concatenate
+	 * @return the SegmentedReadData comprising all the input readDatas
 	 */
 	static SegmentedReadData concatenate(List<SegmentedReadData> readDatas) {
 		return new ConcatenatedReadData(readDatas);
 	}
 
-
-
 	/**
 	 * Returns the location of {@code segment} in this {@code ReadData}.
 	 * <p>
-	 * Note that this {@code ReadData} is not necessarily the source of the segment.
+	 * Note that this {@code ReadData} is not necessarily the source of the
+	 * segment.
 	 * <p>
 	 * The returned {@code Range} may be {@code {offset=0, length=-1}}, which
-	 * means that the segment comprises this whole {@code ReadData} (and the length of
-	 * this {@code ReadData} is not yet known).
+	 * means that the segment comprises this whole {@code ReadData} (and the
+	 * length of this {@code ReadData} is not yet known).
 	 *
 	 * @param segment
-	 * 		the segment id
+	 *            the segment id
 	 *
 	 * @return location of the segment, or null
 	 *
 	 * @throws IllegalArgumentException
-	 * 		if the segment is not contained in this ReadData
+	 *             if the segment is not contained in this ReadData
 	 */
 	Range location(Segment segment) throws IllegalArgumentException;
 
 	/**
-	 * Return all segments (fully) contained in this {@code ReadData}, ordered by location
-	 * (that is, sorted by {@link Range#COMPARATOR}).
+	 * Return all segments (fully) contained in this {@code ReadData}, ordered
+	 * by location (that is, sorted by {@link Range#COMPARATOR}).
 	 *
 	 * @return all segments contained in this {@code ReadData}.
 	 */

src/main/java/org/janelia/saalfeldlab/n5/shard/PositionValueAccess.java

@@ -17,7 +17,15 @@
 public interface PositionValueAccess {
 
 	/**
-	 * @return ReadData for the given key or {@code null} if the key doesn't exist
+	 * Gets the {@link ReadData} for the DataBlock (or shard) at the given
+	 * position in the block (or shard) grid.
+	 * 
+	 * @param key
+	 *            The position of the data block or shard
+	 * @return ReadData for the given key or {@code null} if the key doesn't
+	 *         exist
+	 * @throws N5Exception.N5IOException
+	 *             if an error occurs while reading
 	 */
 	ReadData get(long[] key) throws N5Exception.N5IOException;
 
@@ -53,14 +61,9 @@ class KvaPositionValueAccess implements PositionValueAccess {
 		}
 
 		/**
-		 * Constructs the path for a shard or data block at a given
-		 * grid position.
-		 * <br>
-		 * If the gridPosition passed in refers to shard position in a sharded
-		 * dataset, this will return the path to the shard key.
+		 * Constructs the absolute path for a data block (or shard) at a given grid
+		 * position.
 		 *
-		 * @param normalPath
-		 *            normalized dataset path
 		 * @param gridPosition
 		 *            to the target data block
 		 * @return the absolute path to the data block ad gridPosition

src/main/java/org/janelia/saalfeldlab/n5/shard/RawShard.java

@@ -26,15 +26,20 @@ public class RawShard {
 	}
 
 	/**
-	 * The ReadData from which the shard was constructed, or {@code null}
-	 * for a new empty shard.
+	 * The ReadData from which the shard was constructed, or {@code null} for a
+	 * new empty shard.
+	 * 
+	 * @return this shard's source ReadData, or null.
 	 */
 	public SegmentedReadData sourceData() {
 		return sourceData;
 	}
 
 	/**
-	 * Maps grid position of shard elements to {@link Segment}s.
+	 * Maps grid position of shard elements to {@link Segment}s that give the
+	 * byte range for the blocks in this shard.
+	 * 
+	 * @return an NDArray of segments
 	 */
 	public NDArray<Segment> index() {
 		return index;

src/main/java/org/janelia/saalfeldlab/n5/shard/ShardCodecInfo.java

@@ -9,26 +9,35 @@ public interface ShardCodecInfo extends BlockCodecInfo {
 
 	/**
 	 * Chunk size of each shard element (either nested shard or DataBlock)
+	 * 
+	 * @return the size of each shard element
 	 */
 	int[] getInnerBlockSize();
 
 	/**
-	 * BlockCodec for shard elements (either nested shard or DataBlock)
+	 * BlockCodecInfo for shard elements (either nested shard or DataBlock)
+	 *
+	 * @return the BlockCodecInfo for DataBlocks in this shard
 	 */
 	BlockCodecInfo getInnerBlockCodecInfo();
 
 	/**
-	 * DataCodecs for inner BlockCodec
+	 * @return the collection of DataCodecInfos applied to data blocks for this
+	 *         shard.
 	 */
 	DataCodecInfo[] getInnerDataCodecInfos();
 
 	/**
 	 * BlockCodec for shard index
+	 * 
+	 * @return the BlockCodecInfo for this shard's index
 	 */
 	BlockCodecInfo getIndexBlockCodecInfo();
 
 	/**
 	 * Deterministic-size DataCodecs for index BlockCodec
+	 * 
+	 * @return the collection of DataCodecInfos for this shard's index
 	 */
 	DataCodecInfo[] getIndexDataCodecInfos();