[improve][docs] Improve docs for persistence policies parameters E, Qw and Qa.

[lhotari]

Motivation

Important details are missing for documenting ensemble (E) size, write quorum (Qw) size and ack quorum (Qa) size.
For example, it is not well known that there's a rule that E == Qw to use sticky reads or that the max number of bookie failures is Qa-1. Some might realize this only in production when they lose a bookie and cannot recover.

Modifications

• improve documentation for persistence policies parameters

Documentation

• doc
• doc-required
• doc-not-needed
• doc-complete

Matching PR in forked repository

PR in forked repository:

[eolivelli]

Lgtm

Very useful

[michaeljmarshall]

These are good documentation improvements. I have previously read through the source code to verify this understanding.

I have two comments. The first is about the double negative in the documentation. The second is that sticky reads are also a bookkeeper client feature that likely could be documented on the bookkeeper website.

For example, here is the BK Javadoc for the config: https://github.com/apache/bookkeeper/blob/master/bookkeeper-server/src/main/java/org/apache/bookkeeper/conf/ClientConfiguration.java#L1181-L1198

It's completely off topic for this PR, but I think we could make some form of sticky reads work when E != Qw. Basically, we could make it use a subset of the bookies when doing reads. It wouldn't be completely sticky, but it would take better advantage of the read ahead cache.

[michaeljmarshall]

LGTM

[codecov-commenter]

Codecov Report

❗ No coverage uploaded for pull request base (master@92b4708). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master   #18003   +/-   ##
=========================================
  Coverage          ?   45.72%           
  Complexity        ?    17516           
=========================================
  Files             ?     1573           
  Lines             ?   128211           
  Branches          ?    14098           
=========================================
  Hits              ?    58626           
  Misses            ?    63496           
  Partials          ?     6089           

Flag	Coverage Δ
unittests	45.72% <0.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.