Hi all,
I’m currently going through the english documentation and have noticed a few
things … I guess I’ll be adding more findings as I go along.
General:
* We’re calling the “Data Definition Interface” “DDL” everywhere … however
it should probably be named “DDI” right?
* We’re calling the “Data Manipulation Interface” “DML” … however it should
probably be named “DMI” right?
* We seem to be using both “Schema Template” and “Measurement Template”
mixed throughout the documents.
* InsertTablets seems to receive a “Map” of “path, Tablet” pairs, however
only the Tablet is used, as this contains the path.
* The testInsertXYZ methods claim to be used for testing network as we lase
client costs for an “insertRecord”, but how can I measure these metrics? How
can I distinguish “client time”, “network time” and “server-time”?
* We make very heavy use of the word “Interface”, while sometimes it really
refers to a set of methods or functions, in most cases it’s used for talking
about one individual function or method.
* As we’re generating the python and go sources, why not simply also have
thrift generate the js:node versions too?
C++:
* Here I noticed that the variants not requiring type inference for
insertion add the type-information in the middle of the function signature. I
personally would find it more user-friendly, if this was added last as it
doesn’t change the semantic of the part before.
C#:
* The RowRecord constructor takes the parameters in a differend order
(timestamp, values, measurements) … I would find it more intuitive, if that
was: (timestamp, measurements, values) … just like in the C+ API
* The Tablet has again a completely different order (deviceId,
measurements, values, timestamps) … I would find it more intuitive, if that was
(deviceId, timestampy, measurements, values)
* Many operations in the API define a “CancellationToken”, but this is not
mentioned in the documentation.
* The tables describing the functions only contain the types of the
parameters, also having the name in there might help.
* The tables describing the functions of the APIs don’t show the return
types.
* The tables describing the functions don’t mention what the functions are
used for (TestInsertRecordAsync).
Go:
* The Documentation references Thrift 0.13.0, but the code says we need
0.15.0 but in Java we’re using 0.14.1 (for various reasons)
* The Go API documentation is almost not existent.
* From the prerequisites, I can’t really see why we need “make” and
Windows+bash(WSL, Cygwin, GitBash)
* If I try running the example in “go mod”, I get errors:
cdutz@MBPvonCristofer session_example % go run session_example.go
# command-line-arguments
./session_example.go:478:10: tablet.Reset undefined (type *client.Tablet has no
field or method Reset)
./session_example.go:488:10: tablet.Reset undefined (type *client.Tablet has no
field or method Reset)
./session_example.go:539:10: tablet.RowSize undefined (type *client.Tablet has
no field or method RowSize)
Java:
* Might be worth investigating options to pass in maven parameters as we’re
referencing version 1.0.0 of iotdb-session (just as an example)… would be
better to reference the latest version of the current branch (The snapshot
version for “master” or the “0.13.4” for the 0.13 branch) … in PLC4X we’re
doing exactly that.
* The method: executeLastDataQueryForOneDevice for some reason uses a
completely different approach to address data: Instead of using “path” which
contains db and device, it uses these two separate fields
* The documentation on “Session Pool for Native API” says that there are
multiple occasions, where a SessionDataSetWrapper needs to be closed manually.
Shouldn’t it always be required to close it and as it uses the AutoClosable
interface, shouldn’t a try-with-resources block not automatically handle all
these cases?
* The ClusterInfoService.Client type doesn’t seem to exist.
MQTT
* We’re referencing images from the timecho website, we should probably
integrate the images into the documentation repository.
* In the example custom PayloadFormatter, we should probably point out that
if the Formatter is in a separate jar file and not added to the IoTDB version,
the user needs to create a FAT-jar (containing all dependencies), if he uses
dependencies in it, or he’d have to also copy all dependent jars into the
${IOTDB_HOME}/ext/mqtt/ directory.
NodeJS
* As we’re generating the python and go sources, why not simply also have
thrift generate the js:node versions too?
Python:
* We’re referencing images from the timecho website, we should probably
integrate the images into the documentation repository.
Not yet finished, but that was what I came across in the last two days.
Chris
