Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Introduce @SubclassOptInRequired to codebase and stabilize part of SerialDescriptor's API #2764

Open
wants to merge 3 commits into
base: dev
Choose a base branch
from
Open

Introduce @SubclassOptInRequired to codebase and stabilize part of SerialDescriptor's API #2764

wants to merge 3 commits into from

Commits on Aug 27, 2024

  1. Stabilize most of SerialDescriptor and SerialKind API 

    This API has been around for a long time and has proven itself useful. The main reason @ExperimentalSerializationApi was on SerialDescriptor's properties is that we wanted to discourage people from subclassing it. With the introduction of @SubclassOptInRequired (#2366), we can do this without the need of marking everything with experimental.

Serial kinds fall into the same category with only exception in PolymorphicKind. There are plenty requests for functionality like creating a custom sealed-like descriptor (#2697, #2721, #1865) which may require additional kinds in the future.
    @sandwwraith
    sandwwraith committed Aug 27, 2024
    Configuration menu
    Copy the full SHA
    8577781 View commit details
    Browse the repository at this point in the history

  2. Stabilize SerialDescriptor delegate builder 

    and allow creating primitive descriptors via it as well.

This constructor function is a way to create a descriptor for your
custom serializer if it simply delegates to an existing one.
Since it fits its purpose and is unlikely to change in the future, we can promote it to stable API
alongside other descriptor builders.

Fixes #2547
    @sandwwraith
    sandwwraith committed Aug 27, 2024
    Configuration menu
    Copy the full SHA
    e3cc966 View commit details
    Browse the repository at this point in the history

  3. Introduce @AdvancedEncodingApi and @SealedSerializationApi annotations 

    to be used with @SubclassOptInRequired.

These annotations allow for even more fine-grained API marking. We now can designate APIs
as public for use, but closed for implementation (@SealedSerializationApi) — the case for SerialDescriptor, which is a non-sealed interface for technical reasons.

The other annotation, @AdvancedEncodingApi is aimed to provide guidance on implementing custom encoders/decoders by pointing users to a documentation and guides.

Fixes #2366
    @sandwwraith
    sandwwraith committed Aug 27, 2024
    Configuration menu
    Copy the full SHA
    5d538ee View commit details
    Browse the repository at this point in the history