Doc improvement getCalculatedPending() versus getPendingMessageCount()

[matthewadams]

Overview

Document the proper use, when using an [ordered] push consumer, of

JetStreamSubscription#getConsumerInfo().getCalculatedPending()

versus

JetStreamSubscription#getPendingMessageCount()

Description

For the use case where a stream consumer wants to retrieve all events using a subject filter, it should be documented that the developer should not use JetStreamSubscription#getPendingMessageCount(), and should use JetStreamSubscription#getConsumerInfo().getCalculatedPending(). This was tribally known prior to my filing this issue, but needs to be called out explicitly in the documentation. Further, I think that the javadoc of these properties should be beefed up so that those that are looking at the source understand the differences.

Link to Slack discussion where this is called out: https://natsio.slack.com/archives/C055AB5M1KM/p1689197213989439?thread_ts=1689111301.307819&cid=C055AB5M1KM