[FLINK-26357][format] add FLINK API annotations

[JingGe]

What is the purpose of the change

Add FLINK API annotations to public classes.

Brief change log

• add annotations
• optimize some javadoc

Verifying this change

This change is a trivial code cleanup without any test coverage.

Does this pull request potentially affect one of the following parts:

• Dependencies (does it add or upgrade a dependency): (yes / no)
• The public API, i.e., is any changed class annotated with @Public(Evolving): (yes / no)
• The serializers: (yes / no / don't know)
• The runtime per-record code paths (performance sensitive): (yes / no / don't know)
• Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: (yes / no / don't know)
• The S3 file system connector: (yes / no / don't know)

Documentation

• Does this pull request introduce a new feature? (yes / no)

[flinkbot]

Thanks a lot for your contribution to the Apache Flink project. I'm the @flinkbot. I help the community
to review your pull request. We will use this comment to track the progress of the review.

Automated Checks

Last check on commit 3f271f3 (Thu Feb 24 16:17:58 UTC 2022)

Warnings:

• No documentation files were touched! Remember to keep the Flink docs up to date!

_{Mention the bot in a comment to re-run the automated checks.}

Review Progress

• ❓ 1. The [description] looks good.
• ❓ 2. There is [consensus] that the contribution should go into to Flink.
• ❓ 3. Needs [attention] from.
• ❓ 4. The change fits into the overall [architecture].
• ❓ 5. Overall code [quality] is good.

Please see the Pull Request Review Guide for a full explanation of the review process.

The Bot is tracking the review progress through labels. Labels are applied according to the order of the review items. For consensus, approval by a Flink committer of PMC member is required

Bot commands

The @flinkbot bot supports the following commands:

• @flinkbot approve description to approve one or more aspects (aspects: description, consensus, architecture and quality)
• @flinkbot approve all to approve all aspects
• @flinkbot approve-until architecture to approve everything until architecture
• @flinkbot attention @username1 [@username2 ..] to require somebody's attention
• @flinkbot disapprove architecture to remove an approval you gave earlier

[flinkbot]

CI report:

• fc7fd26 Azure: SUCCESS

Bot commands

The @flinkbot bot supports the following commands:

• @flinkbot run azure re-run the last Azure build

[afedulov]

Thanks for the PR, @JingGe, I added some comments. In general, it looks fine to me, with the exception of two points:

• What is the rationale behind marking the classes as Experimental? The API seems to be pretty tight in terms of input/output parameters, or do you expect potential changes?
• CI is currently failing, but the failures seem to be unrelated to your changes, so try a rebase.

[JingGe]

Thanks for the PR, @JingGe, I added some comments. In general, it looks fine to me, with the exception of two points:

• What is the rationale behind marking the classes as Experimental? The API seems to be pretty tight in terms of input/output parameters, or do you expect potential changes?
• CI is currently failing, but the failures seem to be unrelated to your changes, so try a rebase.

Thanks @afedulov for your effort. I have addressed your comments. The reason of using Experimental is that it is the first time we introduce AvroParquetReaders. I am not pretty sure if there will be any further change request coming from users. It will be upgraded to be PublishEvolving in 1.16 release.

[JingGe]

@flinkbot run azure

[fapaul]

The changes look good but I think it makes sense to change the commit messages slightly to underline which format was changed from [format] -> [avro-parquet]

[JingGe]

Thanks @fapaul for the feedback. Commit messages have been updated. Please help merging the PR. Many thanks!