[Doc] Add descriptions for C++ Client API doc (ClientConfiguration.h …

…+ ConsumerConfiguration.h + ReaderConfiguration.h) (apache#10103)

* [Doc] Add descriptions for C++ Client API doc

* update

* update

* update

Co-authored-by: Anonymitaet <anonymitaet_hotmail.com>

pulsar-client-cpp/include/pulsar/ClientConfiguration.h

@@ -142,29 +142,87 @@ class PULSAR_PUBLIC ClientConfiguration {
      */
     ClientConfiguration& setLogger(LoggerFactory* loggerFactory);
 
+    /**
+     * Configure whether to use the TLS encryption on the connections.
+     *
+     * The default value is false.
+     *
+     * @param useTls
+     */
     ClientConfiguration& setUseTls(bool useTls);
+
+    /**
+     * @return whether the TLS encryption is used on the connections
+     */
     bool isUseTls() const;
 
+    /**
+     * Set the path to the trusted TLS certificate file.
+     *
+     * @param tlsTrustCertsFilePath
+     */
     ClientConfiguration& setTlsTrustCertsFilePath(const std::string& tlsTrustCertsFilePath);
+
+    /**
+     * @return the path to the trusted TLS certificate file
+     */
     std::string getTlsTrustCertsFilePath() const;
 
+    /**
+     * Configure whether the Pulsar client accepts untrusted TLS certificates from brokers.
+     *
+     * The default value is false.
+     *
+     * @param tlsAllowInsecureConnection
+     */
     ClientConfiguration& setTlsAllowInsecureConnection(bool allowInsecure);
+
+    /**
+     * @return whether the Pulsar client accepts untrusted TLS certificates from brokers
+     */
     bool isTlsAllowInsecureConnection() const;
 
+    /**
+     * Configure whether it allows validating hostname verification when a client connects to a broker over
+     * TLS.
+     *
+     * It validates the incoming x509 certificate and matches the provided hostname (CN/SAN) with the
+     * expected broker's hostname. It follows the server identity hostname verification in RFC 2818.
+     *
+     * The default value is false.
+     *
+     * @see [RFC 2818](https://tools.ietf.org/html/rfc2818).
+     *
+     * @param validateHostName whether to enable the TLS hostname verification
+     */
     ClientConfiguration& setValidateHostName(bool validateHostName);
+
+    /**
+     * @return true if the TLS hostname verification is enabled
+     */
     bool isValidateHostName() const;
 
+    /**
+     * Configure the listener name that the broker returns the corresponding `advertisedListener`.
+     *
+     * @param name the listener name
+     */
     ClientConfiguration& setListenerName(const std::string& listenerName);
+
+    /**
+     * @return the listener name for the broker
+     */
     const std::string& getListenerName() const;
 
-    /*
-     * Initialize stats interval in seconds. Stats are printed and reset after every 'statsIntervalInSeconds'.
-     * Set to 0 in order to disable stats collection.
+    /**
+     * Initialize stats interval in seconds. Stats are printed and reset after every `statsIntervalInSeconds`.
+     *
+     * Set to 0 means disabling stats collection.
      */
     ClientConfiguration& setStatsIntervalInSeconds(const unsigned int&);
 
-    /*
-     * Get the stats interval set in the client.
+    /**
+     * @return the stats interval configured for the client
      */
     const unsigned int& getStatsIntervalInSeconds() const;
 

pulsar-client-cpp/include/pulsar/ConsumerConfiguration.h

@@ -89,17 +89,25 @@ class PULSAR_PUBLIC ConsumerConfiguration {
      * consumers will be promoted to primary and will start getting messages.
      */
     ConsumerConfiguration& setConsumerType(ConsumerType consumerType);
+
+    /**
+     * @return the consumer type
+     */
     ConsumerType getConsumerType() const;
 
     /**
      * Set KeyShared subscription policy for consumer.
      *
-     * <p>By default, KeyShared subscription use auto split hash range to maintain consumers. If you want to
+     * By default, KeyShared subscription use auto split hash range to maintain consumers. If you want to
      * set a different KeyShared policy, you can set by following example:
      *
      * @param keySharedPolicy The {@link KeySharedPolicy} want to specify
      */
     ConsumerConfiguration& setKeySharedPolicy(KeySharedPolicy keySharedPolicy);
+
+    /**
+     * @return the KeyShared subscription policy
+     */
     KeySharedPolicy getKeySharedPolicy() const;
 
     /**
@@ -108,37 +116,49 @@ class PULSAR_PUBLIC ConsumerConfiguration {
      * for every message received.
      */
     ConsumerConfiguration& setMessageListener(MessageListener messageListener);
+
+    /**
+     * @return the message listener
+     */
     MessageListener getMessageListener() const;
+
+    /**
+     * @return true if the message listener has been set
+     */
     bool hasMessageListener() const;
 
     /**
      * Sets the size of the consumer receive queue.
      *
-     * The consumer receive queue controls how many messages can be accumulated by the Consumer before the
-     * application calls receive(). Using a higher value could potentially increase the consumer throughput
+     * The consumer receive queue controls how many messages can be accumulated by the consumer before the
+     * application calls receive(). Using a higher value may potentially increase the consumer throughput
      * at the expense of bigger memory utilization.
      *
-     * Setting the consumer queue size as zero decreases the throughput of the consumer, by disabling
+     * Setting the consumer queue size to 0 decreases the throughput of the consumer by disabling
      * pre-fetching of
-     * messages. This approach improves the message distribution on shared subscription, by pushing messages
+     * messages. This approach improves the message distribution on shared subscription by pushing messages
      * only to
-     * the consumers that are ready to process them. Neither receive with timeout nor Partitioned Topics can
+     * the consumers that are ready to process them. Neither receive with timeout nor partitioned topics can
      * be
-     * used if the consumer queue size is zero. The receive() function call should not be interrupted when
-     * the consumer queue size is zero.
+     * used if the consumer queue size is 0. The receive() function call should not be interrupted when
+     * the consumer queue size is 0.
      *
-     * Default value is 1000 messages and should be good for most use cases.
+     * The default value is 1000 messages and it is appropriate for the most use cases.
+     *
+     * @param size the new receiver queue size value
      *
-     * @param size
-     *            the new receiver queue size value
      */
     void setReceiverQueueSize(int size);
+
+    /**
+     * @return the receiver queue size
+     */
     int getReceiverQueueSize() const;
 
     /**
      * Set the max total receiver queue size across partitons.
-     * <p>
-     * This setting will be used to reduce the receiver queue size for individual partitions
+     *
+     * This setting is used to reduce the receiver queue size for individual partitions
      * {@link #setReceiverQueueSize(int)} if the total exceeds this value (default: 50000).
      *
      * @param maxTotalReceiverQueueSizeAcrossPartitions
@@ -150,7 +170,16 @@ class PULSAR_PUBLIC ConsumerConfiguration {
      */
     int getMaxTotalReceiverQueueSizeAcrossPartitions() const;
 
-    void setConsumerName(const std::string&);
+    /**
+     * Set the consumer name.
+     *
+     * @param consumerName
+     */
+    void setConsumerName(const std::string& consumerName);
+
+    /**
+     * @return the consumer name
+     */
     const std::string& getConsumerName() const;
 
     /**
@@ -167,13 +196,27 @@ class PULSAR_PUBLIC ConsumerConfiguration {
      */
     long getUnAckedMessagesTimeoutMs() const;
 
+    /**
+     * Set the tick duration time that defines the granularity of the ack-timeout redelivery (in
+     * milliseconds).
+     *
+     * The default value is 1000, which means 1 second.
+     *
+     * Using a higher tick time reduces
+     * the memory overhead to track messages when the ack-timeout is set to a bigger value.
+     *
+     * @param milliSeconds the tick duration time (in milliseconds)
+     */
     void setTickDurationInMs(const uint64_t milliSeconds);
 
+    /**
+     * @return the tick duration time (in milliseconds)
+     */
     long getTickDurationInMs() const;
 
     /**
      * Set the delay to wait before re-delivering messages that have failed to be process.
-     * <p>
+     *
      * When application uses {@link Consumer#negativeAcknowledge(Message)}, the failed message
      * will be redelivered after a fixed timeout. The default is 1 min.
      *
@@ -235,14 +278,51 @@ class PULSAR_PUBLIC ConsumerConfiguration {
      */
     long getBrokerConsumerStatsCacheTimeInMs() const;
 
+    /**
+     * @return true if encryption keys are added
+     */
     bool isEncryptionEnabled() const;
+
+    /**
+     * @return the shared pointer to CryptoKeyReader.
+     */
     const CryptoKeyReaderPtr getCryptoKeyReader() const;
+
+    /**
+     * Set the shared pointer to CryptoKeyReader.
+     *
+     * @param the shared pointer to CryptoKeyReader
+     */
     ConsumerConfiguration& setCryptoKeyReader(CryptoKeyReaderPtr cryptoKeyReader);
 
+    /**
+     * @return the ConsumerCryptoFailureAction
+     */
     ConsumerCryptoFailureAction getCryptoFailureAction() const;
+
+    /**
+     * Set the ConsumerCryptoFailureAction.
+     */
     ConsumerConfiguration& setCryptoFailureAction(ConsumerCryptoFailureAction action);
 
+    /**
+     * @return true if readCompacted is enabled
+     */
     bool isReadCompacted() const;
+
+    /**
+     * If enabled, the consumer reads messages from the compacted topics rather than reading the full message
+     * backlog of the topic. This means that if the topic has been compacted, the consumer only sees the
+     * latest value for each key in the topic, up until the point in the topic message backlog that has been
+     * compacted. Beyond that point, message is sent as normal.
+     *
+     * `readCompacted` can only be enabled subscriptions to persistent topics, which have a single active
+     * consumer (for example, failure or exclusive subscriptions). Attempting to enable it on subscriptions to
+     * a non-persistent topics or on a shared subscription leads to the subscription call failure.
+     *
+     * @param readCompacted
+     *            whether to read from the compacted topic
+     */
     void setReadCompacted(bool compacted);
 
     /**
@@ -253,9 +333,23 @@ class PULSAR_PUBLIC ConsumerConfiguration {
      * @param periodInSeconds       period in seconds to do an auto discovery
      */
     void setPatternAutoDiscoveryPeriod(int periodInSeconds);
+
+    /**
+     * @return the time duration for the PatternMultiTopicsConsumer performs a pattern auto discovery
+     */
     int getPatternAutoDiscoveryPeriod() const;
 
+    /**
+     * The default value is `InitialPositionLatest`.
+     *
+     * @param subscriptionInitialPosition the initial position at which to set
+     * the cursor when subscribing to the topic for the first time
+     */
     void setSubscriptionInitialPosition(InitialPosition subscriptionInitialPosition);
+
+    /**
+     * @return the configured `InitialPosition` for the consumer
+     */
     InitialPosition getSubscriptionInitialPosition() const;
 
     /**