Section 4.2 is unclear

[njr-11]

While answering a question from a user, I read through section 4.2 on Customizing Property Order and JsonbPropertyOrder Javadoc regarding whether original property names vs customized property names are used in determining the order.

Section 4.2 is unclear because in one place it defers to JsonbPropertyOrder,

To customize the order of serialized properties only for one specific type, JSON Binding provides jakarta.json.bind.annotation.JsonbPropertyOrder annotation. Order specified by JsonbPropertyOrder annotation overrides order specified by PropertyOrderStrategy.

but immediately after that states that The order is applied to already renamed properties as stated in 4.1, which would contradict JsonbPropertyOrder's statement that Names must correspond to original names defined in Java class before any customization applied.

After rereading these seemingly conflicting statements several times over, I finally realized that the line at the end of section 4.2 isn't meant to apply to JsonbPropertyOrder that was discussed immediately before it. Instead, it is intended only for PropertyOrderStrategy.

The PR adds clarification to that line of section 4.2 (first commit). A second commit adds a few grammar corrections that I noticed in that same section. If anyone doesn't want the grammar corrections part, just let me know and I'll remove that commit.

[sean-leichtle]

I'm quite new to Jsonb, so apologies in advance if I've misunderstood something, but annotating a record with @JsonbPropertyOrder doesn't seem to work unless the individual fields in the record are annotated with @JsonbProperty.

That is, the following is deserialized correctly in the order specified by @JsonbPropertyOrder:

@JsonbPropertyOrder({
        "getCommand",
        "getUserName",
})
public record NetworkMessage(
        @JsonbProperty("getCommand") Command getCommand,
        @JsonbProperty("getUserName") String getUserName
) {
    @JsonbCreator
    public NetworkMessage { }
}

The following is not correctly deserialized:

@JsonbPropertyOrder({
        "getCommand",
        "getUserName",
})
public record NetworkMessage(
        Command getCommand,
        String getUserName
) {
    @JsonbCreator
    public NetworkMessage { }
}

I realize records are a special case, but it seems either the end of 4.2 should be amended to read A PropertyOrderStrategy as well as a PropertyOrder used to annotate a record determines the order based on the already renamed properties that have been customized according to the rules outlined under section 4.1. or the JsonbPropertyOrderstatement should be changed to Except in the case of records, names must correspond to original names defined in Java class before any customization applied.