docs: mark the whole Pub/Sub surface as experimental

Tag every command in PubSubCommands with `@api experimental` plus a
visible `@note`, including the eight that remain public (publish,
spublish, the five pubsub_* introspection commands, and the pubsub
convenience method). Pub/Sub is only partially implemented, so none of
it should be read as covered by 1.0.0's semantic-versioning guarantees.

`@api` alone renders nothing in YARD's default template - only
`@api private` has a built-in banner - so each entry pairs the tag with
an `@note`, which does render. The tag stays machine-readable for
`yard list --query '@api.text == "experimental"'` and for
`--hide-api experimental`.

Notes differ by group: the six privatized subscription commands say
withheld-and-raises-NoMethodError, the public ones say usable-but-not-
versioned.

Also fixes the `@api private` tag on pubsub_callback. Trailing prose on
the same line as the tag becomes part of the tag's value, so
`@api private Invoked by...` did not match `@api.text == "private"` and
rendered no private-API banner. Moving the prose to its own line
restores both.

Signed-off-by: Alex Le <alex.le@improving.com>

Author: Aryex

lib/valkey/commands/pubsub_commands.rb

@@ -6,11 +6,19 @@ module Commands
     # Pub/Sub is not yet supported and is partially implemented.
     # Use at your own risks.
     #
+    # @api experimental
+    # @note EXPERIMENTAL: the entire Pub/Sub surface is subject to change and
+    #   is not covered by semantic versioning.
+    #
     # @see https://valkey.io/commands/#pubsub
     #
     module PubSubCommands
       # Subscribe to one or more channels.
       #
+      # @api experimental
+      # @note EXPERIMENTAL and withheld: private for 1.0.0 because the message
+      #   delivery path is incomplete. Calling this raises NoMethodError.
+      #
       # @param [Array<String>] channels the channels to subscribe to
       # @return [String] "OK"
       #
@@ -21,6 +29,10 @@ def subscribe(*channels)
 
       # Unsubscribe from one or more channels.
       #
+      # @api experimental
+      # @note EXPERIMENTAL and withheld: private for 1.0.0 because the message
+      #   delivery path is incomplete. Calling this raises NoMethodError.
+      #
       # @param [Array<String>] channels the channels to unsubscribe from (empty for all)
       # @return [String] "OK"
       #
@@ -31,6 +43,10 @@ def unsubscribe(*channels)
 
       # Subscribe to one or more patterns.
       #
+      # @api experimental
+      # @note EXPERIMENTAL and withheld: private for 1.0.0 because the message
+      #   delivery path is incomplete. Calling this raises NoMethodError.
+      #
       # @param [Array<String>] patterns the patterns to subscribe to
       # @return [String] "OK"
       #
@@ -41,6 +57,10 @@ def psubscribe(*patterns)
 
       # Unsubscribe from one or more patterns.
       #
+      # @api experimental
+      # @note EXPERIMENTAL and withheld: private for 1.0.0 because the message
+      #   delivery path is incomplete. Calling this raises NoMethodError.
+      #
       # @param [Array<String>] patterns the patterns to unsubscribe from (empty for all)
       # @return [String] "OK"
       #
@@ -51,6 +71,10 @@ def punsubscribe(*patterns)
 
       # Publish a message to a channel.
       #
+      # @api experimental
+      # @note EXPERIMENTAL: usable today, but part of the Pub/Sub surface and
+      #   not covered by semantic versioning; may change in a future minor.
+      #
       # @example Publish a message
       #   valkey.publish("channel1", "Hello, World!")
       #     # => 2
@@ -66,6 +90,10 @@ def publish(channel, message)
 
       # Subscribe to one or more shard channels.
       #
+      # @api experimental
+      # @note EXPERIMENTAL and withheld: private for 1.0.0 because the message
+      #   delivery path is incomplete. Calling this raises NoMethodError.
+      #
       # @param [Array<String>] channels the shard channels to subscribe to
       # @return [String] "OK"
       #
@@ -76,6 +104,10 @@ def ssubscribe(*channels)
 
       # Unsubscribe from one or more shard channels.
       #
+      # @api experimental
+      # @note EXPERIMENTAL and withheld: private for 1.0.0 because the message
+      #   delivery path is incomplete. Calling this raises NoMethodError.
+      #
       # @param [Array<String>] channels the shard channels to unsubscribe from (empty for all)
       # @return [String] "OK"
       #
@@ -86,6 +118,10 @@ def sunsubscribe(*channels)
 
       # Publish a message to a shard channel.
       #
+      # @api experimental
+      # @note EXPERIMENTAL: usable today, but part of the Pub/Sub surface and
+      #   not covered by semantic versioning; may change in a future minor.
+      #
       # @example Publish a message to a shard channel
       #   valkey.spublish("shard1", "Hello, Shard!")
       #     # => 1
@@ -101,6 +137,10 @@ def spublish(channel, message)
 
       # List active channels.
       #
+      # @api experimental
+      # @note EXPERIMENTAL: usable today, but part of the Pub/Sub surface and
+      #   not covered by semantic versioning; may change in a future minor.
+      #
       # @example List all active channels
       #   valkey.pubsub_channels
       #     # => ["channel1", "channel2"]
@@ -119,6 +159,10 @@ def pubsub_channels(pattern = nil)
 
       # Get the number of unique patterns subscribed to.
       #
+      # @api experimental
+      # @note EXPERIMENTAL: usable today, but part of the Pub/Sub surface and
+      #   not covered by semantic versioning; may change in a future minor.
+      #
       # @example Get pattern count
       #   valkey.pubsub_numpat
       #     # => 3
@@ -132,6 +176,10 @@ def pubsub_numpat
 
       # Get the number of subscribers for channels.
       #
+      # @api experimental
+      # @note EXPERIMENTAL: usable today, but part of the Pub/Sub surface and
+      #   not covered by semantic versioning; may change in a future minor.
+      #
       # @example Get subscriber counts
       #   valkey.pubsub_numsub("channel1", "channel2")
       #     # => ["channel1", 5, "channel2", 3]
@@ -146,6 +194,10 @@ def pubsub_numsub(*channels)
 
       # List active shard channels.
       #
+      # @api experimental
+      # @note EXPERIMENTAL: usable today, but part of the Pub/Sub surface and
+      #   not covered by semantic versioning; may change in a future minor.
+      #
       # @example List all active shard channels
       #   valkey.pubsub_shardchannels
       #     # => ["shard1", "shard2"]
@@ -164,6 +216,10 @@ def pubsub_shardchannels(pattern = nil)
 
       # Get the number of subscribers for shard channels.
       #
+      # @api experimental
+      # @note EXPERIMENTAL: usable today, but part of the Pub/Sub surface and
+      #   not covered by semantic versioning; may change in a future minor.
+      #
       # @example Get shard subscriber counts
       #   valkey.pubsub_shardnumsub("shard1", "shard2")
       #     # => ["shard1", 2, "shard2", 1]
@@ -178,6 +234,12 @@ def pubsub_shardnumsub(*channels)
 
       # Control pub/sub operations (convenience method).
       #
+      # @api experimental
+      # @note EXPERIMENTAL: usable today, but part of the Pub/Sub surface and
+      #   not covered by semantic versioning; may change in a future minor.
+      #   Only the introspection subcommands are reachable - `channels`,
+      #   `numpat`, `numsub`, `shardchannels`, `shardnumsub`.
+      #
       # @example List active channels
       #   valkey.pubsub(:channels)
       #     # => ["channel1", "channel2"]

lib/valkey/pubsub_callback.rb

@@ -10,10 +10,17 @@ class Valkey
   # vector, so it is private - `Valkey#initialize` still reaches it via
   # `method(:pubsub_callback)`, which resolves private methods and preserves
   # arity.
+  # @api private
+  # @note EXPERIMENTAL: part of the unfinished Pub/Sub surface; not covered by
+  #   semantic versioning.
   module PubSubCallback
     private
 
-    # @api private Invoked by libglide_ffi on an incoming Pub/Sub push message.
+    # Invoked by libglide_ffi on an incoming Pub/Sub push message.
+    #
+    # @api private
+    # @note EXPERIMENTAL: signature is dictated by the FFI callback contract and
+    #   may change when full Pub/Sub support lands.
     def pubsub_callback(_client_ptr, kind, msg_ptr, msg_len, chan_ptr, chan_len, pat_ptr, pat_len)
       puts "PubSub received kind=#{kind}, message=#{msg_ptr.read_string(msg_len)}" \
            ", channel=#{chan_ptr.read_string(chan_len)}, pattern=#{pat_ptr.read_string(pat_len)}"