More docs for Java examples?
- Dominant language
- Java
- Stars
- 203
- Forks
- 104
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 33
Description
The Java examples are poorly documented. The only page mentioning the examples is the [QuickStart](https://tsfile.apache.org/zh/UserGuide/latest/QuickStart/QuickStart.html) tutorial. I encountered a few questions while studying the examples:
First, how to run the examples? I cloned the repository and built the Java packages, but can't figure out how to run the examples. Copilot gave me the following command:
```
$ ./mvnw -f java/examples/pom.xml -DskipTests exec:java -Dexec.mainClass=org.apache.tsfile.XXX
```
Is this correct?
Second, what are the functions of each example? The only two examples mentioned by QuickStart are `org.apache.tsfile.v4.WriteTabletWithITsFileWriter` (for writing TsFiles) and `org.apache.tsfile.v4.ITsFileReaderAndITsFileWriter` (for reading and writing TsFiles), and it seems that the former one is just a subset of the latter one. Besides, both of them are prefixed with `v4`. This is confusing because TsFile Java only has v1 and v2. What does v4 stand for? Does that mean that examples outside the `v4` package are outdated?
Finally, I stumbled upon the [TsFile API](https://tsfile.apache.org/zh/stage/QuickStart.html) page, which doesn't have any backlinks. I noticed that it is under the "stage" directory, is it a "staging" page? Will it be published one day?
Above all, could you please provide more docs for the Java examples?
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the QuickStart page, java/examples/pom.xml, and the example classes named in the issue, including the org.apache.tsfile.v4 examples. Document how to run the Java examples, explain each example and the v4 naming, and clarify the status of the TsFile API page under stage; done means these questions are answered in discoverable documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100