Blank?

I was trying to follow what I thought was the existing convention, i.e.:

Jwts.parser()

    .setSigningKeyResolver(signingKeyResolver) // <----
    
    .parseClaimsJws(jwsString);

My personal pref is would be to strip those empty lines

Ah, I see what we did - it was to make it more visually obvious as to what is calling attention. Let's stick to the current convention, and we can have another PR if we want to change that convention.

Now that I'm looking at it, the extra lines with the // <----- makes it more visually obvious and probably enhances readability. Just my .02 though.

Shouldn't we show the constructor with ObjectMapper as an argument?

This constructor will create and manipulate a new ObjectMapper (conventionally mapping the claims to types). This could cause unforeseen issues with an existing object mapper.

Anything more advanced then this, the JacksonDeserializer(ObjectMapper) constructor should be used instead (as shown in the previous section).

My point is shouldn't there be a JacksonDeserializer(ObjectMapper, Map) constructor?

No, I think if you want to use a custom ObjectMapper, you would be in charge of configuring that instance. This constructor modifies the ObjectMapper, which could invalidate, or worse only slightly change how the ObjectMapper was originally configured.

You could end up in a situation where the same ObjectMapper is used for a few requests, then a JwtParser is constructed for the first time (with JacksonDeserializer(ObjectMapper, Map)) and this could change how future requests were parsed with the ObjectMapper in that application. For example, I couldn't use JacksonSerializer.DEFAULT_OBJECT_MAPPER for the same reason, as it would have changed how other JacksonDeserializers would parse.

That said this issue is specific to the readme, lets me move this over to #495 (I'll come back and tweak the doc with the signatures that we agree with)
https://github.com/jwtk/jjwt/pull/495/files#diff-43ca7dcadb15963ec66e63df02544e1aR68

Ah, ok, this is super helpful.

I think we need to be super clear about this in the documentation. For example, the very first sentence in the first section on Jackson states:

If you have an application-wide Jackson ObjectMapper (as is typically recommended for most applications), you can eliminate the overhead of JJWT constructing its own ObjectMapper by using yours instead.

I'm sure people would be curious why they can use their own ObjectMapper in one scenario, but not another, so this should be crystal clear in the docs IMO (i.e. in this PR).

Why the blank line? I don't think we do this in other parts of the doc, do we? Whatever we do, we should keep it consistent.

I was just trying to follow what I thought was the existing format, i.e.:

Jwts.parser()
    
    .setAllowedClockSkewSeconds(seconds) // <----
    
    // ... etc ...
    .parseClaimsJws(jwt);

My personal pref would be to strip the empty lines. My assumption was probably wrong, maybe the convention is to insert a new line between each line of code? (and keep any relevant comments directly above a given line)

Blank?

Ah, based on current convention, let's add a // <----- comment at the end of line 1340

Ah, ok, this is super helpful.

I think we need to be super clear about this in the documentation. For example, the very first sentence in the first section on Jackson states:

If you have an application-wide Jackson ObjectMapper (as is typically recommended for most applications), you can eliminate the overhead of JJWT constructing its own ObjectMapper by using yours instead.

I'm sure people would be curious why they can use their own ObjectMapper in one scenario, but not another, so this should be crystal clear in the docs IMO (i.e. in this PR).