doc(java) fix comments

thulab · Dec 18, 2018 · 1dc6f51 · 1dc6f51
1 parent 4c9ce6a
commit 1dc6f51
Show file tree

Hide file tree

Showing 34 changed files with 213 additions and 130 deletions.
diff --git a/src/main/java/cn/edu/tsinghua/tsfile/common/utils/Binary.java b/src/main/java/cn/edu/tsinghua/tsfile/common/utils/Binary.java
@@ -21,7 +21,7 @@ public class Binary implements Comparable<Binary>, Serializable {
 
     /**
      * if the bytes v is modified, the modification is visable to this binary.
-     * @param v
+     * @param v value
      */
     public Binary(byte[] v) {
         this.values = v;

diff --git a/src/main/java/cn/edu/tsinghua/tsfile/common/utils/ReadWriteForEncodingUtils.java b/src/main/java/cn/edu/tsinghua/tsfile/common/utils/ReadWriteForEncodingUtils.java
@@ -130,7 +130,7 @@ public static void writeUnsignedVarInt(int value, OutputStream out) throws IOExc
      *
      *
      * @param value value to write into stream
-     * @param buffer where to store the result. buffer.remaining() needs to >= 32.
+     * @param buffer where to store the result. buffer.remaining() needs to larger than or equal to 32.
      *               Notice: (1) this function does not check buffer's remaining().
      *              (2) the position will be updated.
      * @return the number of bytes that the value consume.

diff --git a/src/main/java/cn/edu/tsinghua/tsfile/common/utils/ReadWriteIOUtils.java b/src/main/java/cn/edu/tsinghua/tsfile/common/utils/ReadWriteIOUtils.java
@@ -255,6 +255,10 @@ public static String readStringFromDirectByteBuffer(ByteBuffer buffer) throws Ch
 
     /**
      * unlike InputStream.read(bytes), this method makes sure that you can read length bytes or reach to the end of the stream.
+     * @param inputStream input stream
+     * @param length read length
+     * @return read Bytes
+     * @throws IOException IOException
      */
     public static byte[] readBytes(InputStream inputStream, int length) throws IOException {
         byte[] bytes=new byte[length];
@@ -268,6 +272,9 @@ public static byte[] readBytes(InputStream inputStream, int length) throws IOExc
 
     /**
      * unlike InputStream.read(bytes), this method makes sure that you can read length bytes or reach to the end of the stream.
+     * @param inputStream input stream
+     * @return read Bytes
+     * @throws IOException IOException
      */
     public static byte[] readBytesWithSelfDescriptionLength(InputStream inputStream) throws IOException {
         int length=readInt(inputStream);
@@ -326,11 +333,6 @@ public static int readAsPossible(FileChannel channel, ByteBuffer buffer, int len
         return length;
     }
 
-
-
-    /**
-     * List<Integer>
-     */
     public static List<Integer> readIntegerList(InputStream inputStream) throws IOException {
         int size = readInt(inputStream);
         if(size <= 0)return null;
@@ -341,6 +343,7 @@ public static List<Integer> readIntegerList(InputStream inputStream) throws IOEx
 
         return list;
     }
+
     public static List<Integer> readIntegerList(ByteBuffer buffer) throws IOException {
         int size = readInt(buffer);
         if(size <= 0)return null;
@@ -371,9 +374,12 @@ public static List<String> readStringList(ByteBuffer buffer) throws IOException
         return list;
     }
 
-
     /**
-     * CompressionType
+     * write Compression
+     * @param compressionType Compression Type
+     * @param outputStream outputStream
+     * @return bytes length
+     * @throws IOException IOException
      */
     public static int write(CompressionType compressionType, OutputStream outputStream) throws IOException {
         short n = compressionType.serialize();
@@ -394,9 +400,6 @@ public static CompressionType readCompressionType(ByteBuffer buffer) {
     }
 
 
-    /**
-     * TSDataType
-     */
     public static int write(TSDataType dataType, OutputStream outputStream) throws IOException {
         short n = dataType.serialize();
         return write(n, outputStream);
@@ -416,9 +419,6 @@ public static TSDataType readDataType(ByteBuffer buffer) {
     }
 
 
-    /**
-     * TSEncoding
-     */
     public static int write(TSEncoding encoding, OutputStream outputStream) throws IOException {
         short n = encoding.serialize();
         return write(n, outputStream);
@@ -438,9 +438,6 @@ public static TSEncoding readEncoding(ByteBuffer buffer) {
     }
 
 
-    /**
-     * TSFreqType
-     */
     public static int write(TSFreqType freqType, OutputStream outputStream) throws IOException {
         short n = freqType.serialize();
         return write(n, outputStream);

diff --git a/src/main/java/cn/edu/tsinghua/tsfile/compress/Compressor.java b/src/main/java/cn/edu/tsinghua/tsfile/compress/Compressor.java
@@ -42,12 +42,12 @@ public static Compressor getCompressor(CompressionType name) {
 
     /**
      *
-     * @param data
-     * @param offset
-     * @param length
-     * @param compressed
+     * @param data MUST be byte[]
+     * @param offset offset of data
+     * @param length length of data
+     * @param compressed MUST be byte[]
      * @return byte length of compressed data.
-     * @throws IOException
+     * @throws IOException IOException
      */
     public abstract  int  compress(byte[] data, int offset, int length, byte[] compressed) throws IOException;
 
@@ -56,7 +56,7 @@ public static Compressor getCompressor(CompressionType name) {
      * @param data MUST be DirectByteBuffer  for Snappy.
      * @param compressed MUST be DirectByteBuffer for Snappy.
      * @return byte length of compressed data.
-     * @throws IOException
+     * @throws IOException IOException
      */
     public abstract int compress(ByteBuffer data, ByteBuffer compressed) throws IOException;
 

diff --git a/src/main/java/cn/edu/tsinghua/tsfile/compress/UnCompressor.java b/src/main/java/cn/edu/tsinghua/tsfile/compress/UnCompressor.java
@@ -38,8 +38,8 @@ public static UnCompressor getUnCompressor(CompressionType name) {
     /**
      *
      * @param buffer MUST be DirectByteBuffer
-     * @return
-     * @throws IOException
+     * @return Uncompressed length
+     * @throws IOException IOException
      */
     public abstract int getUncompressedLength(ByteBuffer buffer) throws IOException;
 
@@ -52,20 +52,22 @@ public static UnCompressor getUnCompressor(CompressionType name) {
 
     /**
      *
-     * @param byteArray
-     * @param offset
-     * @param length
-     * @param output
-     * @param outOffset
+     * @param byteArray to be uncompressed bytes
+     * @param offset offset
+     * @param length length
+     * @param output MUST be byte[]
+     * @param outOffset output offset
      * @return the valid length of the output array
+     * @throws IOException IOException
      */
     public abstract  int uncompress(byte[] byteArray, int offset, int length, byte[] output, int outOffset)  throws IOException ;
 
     /**
      * if the data is large, using this function is better.
      * @param compressed MUST be DirectByteBuffer
      * @param uncompressed MUST be DirectByteBuffer
-     * @return
+     * @return the valid length
+     * @throws IOException IOException
      */
     public abstract int uncompress(ByteBuffer compressed, ByteBuffer uncompressed)   throws IOException ;
 

diff --git a/src/main/java/cn/edu/tsinghua/tsfile/file/footer/RowGroupFooter.java b/src/main/java/cn/edu/tsinghua/tsfile/file/footer/RowGroupFooter.java
@@ -61,10 +61,10 @@ public int serializeTo(OutputStream outputStream) throws IOException {
     }
 
     /**
-     * @param inputStream
+     * @param inputStream input stream
      * @param markerRead  Whether the marker of the RowGroupFooter is read ahead.
-     * @return
-     * @throws IOException
+     * @return deserialized RowGroupFooter
+     * @throws IOException IOException
      */
     public static RowGroupFooter deserializeFrom(InputStream inputStream, boolean markerRead) throws IOException {
         if (!markerRead) {

diff --git a/src/main/java/cn/edu/tsinghua/tsfile/file/header/ChunkHeader.java b/src/main/java/cn/edu/tsinghua/tsfile/file/header/ChunkHeader.java
@@ -97,10 +97,10 @@ public int serializeTo(ByteBuffer buffer) {
     }
 
     /**
-     * @param inputStream
+     * @param inputStream input stream
      * @param markerRead  Whether the marker of the ChunkHeader has been read
-     * @return
-     * @throws IOException
+     * @return deserialized ChunkHeader
+     * @throws IOException IOException
      */
     public static ChunkHeader deserializeFrom(InputStream inputStream, boolean markerRead) throws IOException {
         if (!markerRead) {

diff --git a/src/main/java/cn/edu/tsinghua/tsfile/file/metadata/TsFileMetaData.java b/src/main/java/cn/edu/tsinghua/tsfile/file/metadata/TsFileMetaData.java
@@ -39,6 +39,8 @@ public TsFileMetaData() {
     }
 
     /**
+     *
+     * @param deviceMap         - device map (String, TsDeviceMetadata)
      * @param measurementSchema - time series info list
      * @param currentVersion    - current version
      */

diff --git a/src/main/java/cn/edu/tsinghua/tsfile/file/metadata/statistics/Statistics.java b/src/main/java/cn/edu/tsinghua/tsfile/file/metadata/statistics/Statistics.java
@@ -170,7 +170,7 @@ public void reset() {
      *     boolean - 1 <br>
      *     No - 0 <br>
      *     binary - -1 which means uncertainty
-     *     </>
+     *
      */
     abstract public int sizeOfDatum();
 

diff --git a/src/main/java/cn/edu/tsinghua/tsfile/timeseries/read/TsFileSequenceReader.java b/src/main/java/cn/edu/tsinghua/tsfile/timeseries/read/TsFileSequenceReader.java
@@ -37,10 +37,8 @@ public TsFileSequenceReader(String file) throws IOException {
     }
 
     /**
-     * After open the file, the reader position is at the end of the  magic string in the header.
-     *
-     * @return
-     * @throws IOException
+     * After open the file, the reader position is at the end of the magic string in the header.
+     * @throws IOException IOException
      */
     private void open() throws IOException {
         channel = FileChannel.open(path, StandardOpenOption.READ);
@@ -55,8 +53,8 @@ private void open() throws IOException {
     /**
      * this function does not modify the position of the file reader.
      *
-     * @return
-     * @throws IOException
+     * @return magic string bytes array in string format
+     * @throws IOException IOException
      */
     public String readTailMagic() throws IOException {
         long totalSize = channel.size();
@@ -69,8 +67,8 @@ public String readTailMagic() throws IOException {
     /**
      * this function does not modify the position of the file reader.
      *
-     * @return
-     * @throws IOException
+     * @return magic string bytes array in string format
+     * @throws IOException IOException
      */
     public String readHeadMagic() throws IOException {
         ByteBuffer magicStringBytes = ByteBuffer.allocate(TSFileConfig.MAGIC_STRING.length());
@@ -82,8 +80,8 @@ public String readHeadMagic() throws IOException {
     /**
      * this function does not modify the position of the file reader.
      *
-     * @return
-     * @throws IOException
+     * @return deserialized TsFile metadata
+     * @throws IOException IOException
      */
     public TsFileMetaData readFileMetadata() throws IOException {
         ByteBuffer buffer = ByteBuffer.allocate(fileMetadtaSize);
@@ -104,8 +102,8 @@ public RowGroupFooter readRowGroupFooter() throws IOException {
      * After reading the footer of a RowGroup, call this method to set the file pointer to the start of the data of this
      * RowGroup if you want to read its data next.
      *
-     * @param footer
-     * @throws IOException
+     * @param footer row group footer
+     * @throws IOException IOException
      */
     public void prepareReadRowGroup(RowGroupFooter footer) throws IOException {
         channel.position(channel.position() - footer.getDataSize() - footer.getSerializedSize());
@@ -119,8 +117,8 @@ public ChunkHeader readChunkHeader() throws IOException {
      * notice, this function will modify channel's position.
      *
      * @param offset the file offset of this chunk's header
-     * @return
-     * @throws IOException
+     * @return deserialized chunk header
+     * @throws IOException IOException
      */
     public ChunkHeader readChunkHeader(long offset) throws IOException {
         channel.position(offset);
@@ -130,9 +128,9 @@ public ChunkHeader readChunkHeader(long offset) throws IOException {
     /**
      * notice, the position of the channel MUST be at the end of this header.
      *
-     * @param header
+     * @param header chunk header
      * @return the pages of this chunk
-     * @throws IOException
+     * @throws IOException IOException
      */
     public ByteBuffer readChunk(ChunkHeader header) throws IOException {
         ByteBuffer buffer = ByteBuffer.allocate(header.getDataSize());
@@ -144,9 +142,9 @@ public ByteBuffer readChunk(ChunkHeader header) throws IOException {
     /**
      * notice, this function will modify channel's position.
      *
-     * @param position
-     * @return
-     * @throws IOException
+     * @param position read chunk header position
+     * @return chunk and header in ByteBuffer format
+     * @throws IOException IOException
      */
     public ByteBuffer readChunkAndHeader(long position) throws IOException {
         ChunkHeader header = readChunkHeader(position);
@@ -158,13 +156,13 @@ public ByteBuffer readChunkAndHeader(long position) throws IOException {
     }
 
     /**
-     * notice, the function will midify channel's position.
+     * notice, the function will modify channel's position.
      *
-     * @param position
-     * @param length
-     * @param output
-     * @return
-     * @throws IOException
+     * @param position channel start position
+     * @param length read length of raw ByteBuffer
+     * @param output output in ByteBuffer format
+     * @return read length
+     * @throws IOException IOException
      */
     public int readRaw(long position, int length, ByteBuffer output) throws IOException {
         channel.position(position);
@@ -174,9 +172,10 @@ public int readRaw(long position, int length, ByteBuffer output) throws IOExcept
     /**
      * notice, this function will modify channel's position.
      *
-     * @param header
+     * @param header chunk header
+     * @param positionOfChunkHeader position of chunk header
      * @return the pages of this chunk
-     * @throws IOException
+     * @throws IOException IOException
      */
     public ByteBuffer readChunk(ChunkHeader header, long positionOfChunkHeader) throws IOException {
         channel.position(positionOfChunkHeader);
@@ -190,9 +189,10 @@ public PageHeader readPageHeader(TSDataType type) throws IOException {
     /**
      * notice, this function will modify channel's position.
      *
+     * @param type time series data type
      * @param offset the file offset of this page header's header
-     * @return
-     * @throws IOException
+     * @return page header
+     * @throws IOException IOException
      */
     public PageHeader readPageHeader(TSDataType type, long offset) throws IOException {
         channel.position(offset);

diff --git a/src/main/java/cn/edu/tsinghua/tsfile/timeseries/read/controller/SeriesChunkLoader.java b/src/main/java/cn/edu/tsinghua/tsfile/timeseries/read/controller/SeriesChunkLoader.java
@@ -12,6 +12,9 @@ public interface SeriesChunkLoader {
 
     /**
      * read all content of any chunk
+     * @param chunkMetaData chunk meta data
+     * @return SeriesChunk
+     * @throws IOException IOException
      */
     SeriesChunk getMemSeriesChunk(ChunkMetaData chunkMetaData) throws IOException;
 }
diff --git a/src/main/java/cn/edu/tsinghua/tsfile/timeseries/read/datatype/RowRecord.java b/src/main/java/cn/edu/tsinghua/tsfile/timeseries/read/datatype/RowRecord.java
@@ -23,17 +23,17 @@ private RowRecord() {
 
     /**
      * init this.fields and set time stamp
-     * @param timestamp
+     * @param timestamp timestamp
      */
     public RowRecord(long timestamp) {
         this();
         this.timestamp = timestamp;
     }
 
     /**
-     * add one <path, field>
-     * @param path
-     * @param tsPrimitiveType
+     * add one (path, field) tuple to fields map which contains all value fields of the record
+     * @param path a series in delta system
+     * @param tsPrimitiveType time series primitive type
      */
     public void putField(Path path, TsPrimitiveType tsPrimitiveType) {
         fields.put(path, tsPrimitiveType);