Use proper deprecated tags for doxygen

Author: alan-george-lk

AGENTS.md

@@ -146,6 +146,32 @@ All source files must have the LiveKit Apache 2.0 copyright header. Use the curr
 - `lk_log.h` lives under `src/` (internal). The public-facing logging API is `include/livekit/logging.h`.
 - spdlog must not appear in any public header or installed header.
 
+#### Deprecating a public API
+
+When superseding a public API (renaming, replacing, or removing in a future major
+version), every retained back-compat shim must carry **both** annotations:
+
+1. The C++11 `[[deprecated("...")]]` attribute so the compiler warns at every
+   call site. The message should name the replacement (e.g.
+   `"AudioFrame::sample_rate is deprecated; use AudioFrame::sampleRate instead"`).
+2. A Doxygen `/// @deprecated Use <newName>() instead.` line immediately above
+   the attribute so the generated docs render a deprecation callout and add the
+   symbol to Doxygen's auto-generated *Deprecated List* page. Doxygen does not
+   read the C++ attribute, so this line is required even though it duplicates
+   information.
+
+Example:
+
+```cpp
+/// @deprecated Use sampleRate() instead.
+[[deprecated("AudioFrame::sample_rate is deprecated; use AudioFrame::sampleRate instead")]]
+int sample_rate() const noexcept { return sampleRate(); }
+```
+
+Keep the prose consistent: `Use <newName>() instead.` Per-symbol deprecations
+must use `///` (not `//`); only section-level asides (e.g. "Deprecated public
+mutators" group headers) may stay as plain `//` comments.
+
 ### Include Conventions
 
 - **Public headers (`include/livekit/*.h`) must include other public headers

include/livekit/audio_frame.h

@@ -86,31 +86,31 @@ class LIVEKIT_API AudioFrame {
   /// A human-readable description.
   std::string toString() const;
 
-  // Deprecated - see totalSamples()
+  /// @deprecated Use totalSamples() instead.
   [[deprecated("AudioFrame::total_samples is deprecated; use AudioFrame::totalSamples instead")]]
   std::size_t total_samples() const noexcept { // NOLINT(readability-identifier-naming)
     return totalSamples();
   }
 
-  // Deprecated - see sampleRate()
+  /// @deprecated Use sampleRate() instead.
   [[deprecated("AudioFrame::sample_rate is deprecated; use AudioFrame::sampleRate instead")]]
   int sample_rate() const noexcept { // NOLINT(readability-identifier-naming)
     return sampleRate();
   }
 
-  // Deprecated - see numChannels()
+  /// @deprecated Use numChannels() instead.
   [[deprecated("AudioFrame::num_channels is deprecated; use AudioFrame::numChannels instead")]]
   int num_channels() const noexcept { // NOLINT(readability-identifier-naming)
     return numChannels();
   }
 
-  // Deprecated - see samplesPerChannel()
+  /// @deprecated Use samplesPerChannel() instead.
   [[deprecated("AudioFrame::samples_per_channel is deprecated; use AudioFrame::samplesPerChannel instead")]]
   int samples_per_channel() const noexcept { // NOLINT(readability-identifier-naming)
     return samplesPerChannel();
   }
 
-  // Deprecated - see toString()
+  /// @deprecated Use toString() instead.
   [[deprecated("AudioFrame::to_string is deprecated; use AudioFrame::toString instead")]]
   std::string to_string() const; // NOLINT(readability-identifier-naming)
 

include/livekit/audio_source.h

@@ -86,19 +86,19 @@ class LIVEKIT_API AudioSource {
   /// Underlying FFI handle ID used in FFI requests.
   std::uint64_t ffiHandleId() const noexcept { return static_cast<std::uint64_t>(handle_.get()); }
 
-  // Deprecated - see sampleRate()
+  /// @deprecated Use sampleRate() instead.
   [[deprecated("AudioSource::sample_rate is deprecated; use AudioSource::sampleRate instead")]]
   int sample_rate() const noexcept { // NOLINT(readability-identifier-naming)
     return sampleRate();
   }
 
-  // Deprecated - see numChannels()
+  /// @deprecated Use numChannels() instead.
   [[deprecated("AudioSource::num_channels is deprecated; use AudioSource::numChannels instead")]]
   int num_channels() const noexcept { // NOLINT(readability-identifier-naming)
     return numChannels();
   }
 
-  // Deprecated - see ffiHandleId()
+  /// @deprecated Use ffiHandleId() instead.
   [[deprecated("AudioSource::ffi_handle_id is deprecated; use AudioSource::ffiHandleId instead")]]
   std::uint64_t ffi_handle_id() const noexcept { // NOLINT(readability-identifier-naming)
     return ffiHandleId();

include/livekit/local_audio_track.h

@@ -79,7 +79,7 @@ class LIVEKIT_API LocalAudioTrack : public Track {
   /// including its SID and name. Useful for debugging and logging.
   std::string toString() const;
 
-  // Deprecated - see toString()
+  /// @deprecated Use toString() instead.
   // NOLINTBEGIN(readability-identifier-naming)
   [[deprecated("LocalAudioTrack::to_string is deprecated; use LocalAudioTrack::toString instead")]]
   std::string to_string() const;

include/livekit/local_video_track.h

@@ -79,7 +79,7 @@ class LIVEKIT_API LocalVideoTrack : public Track {
   /// including its SID and name. Useful for debugging and logging.
   std::string toString() const;
 
-  // Deprecated - see toString()
+  /// @deprecated Use toString() instead.
   // NOLINTBEGIN(readability-identifier-naming)
   [[deprecated("LocalVideoTrack::to_string is deprecated; use LocalVideoTrack::toString instead")]]
   std::string to_string() const;

include/livekit/participant.h

@@ -60,43 +60,43 @@ class LIVEKIT_API Participant {
 
   // NOLINTBEGIN(readability-identifier-naming)
 
-  // Deprecated - see setName() (also deprecated; see notes above).
+  /// @deprecated Use setName() instead.
   [[deprecated("Participant::set_name is deprecated; use LocalParticipant::setName instead")]]
   void set_name(std::string name) noexcept {
     name_ = std::move(name);
   }
 
-  // Deprecated - see setMetadata() (also deprecated; see notes above).
+  /// @deprecated Use setMetadata() instead.
   [[deprecated("Participant::set_metadata is deprecated; use LocalParticipant::setMetadata instead")]]
   void set_metadata(std::string metadata) noexcept {
     metadata_ = std::move(metadata);
   }
 
-  // Deprecated - see setAttributes() (also deprecated; see notes above).
+  /// @deprecated Use setAttributes() instead.
   [[deprecated("Participant::set_attributes is deprecated; use LocalParticipant::setAttributes instead")]]
   void set_attributes(std::unordered_map<std::string, std::string> attrs) noexcept {
     attributes_ = std::move(attrs);
   }
 
-  // Deprecated - see setAttribute() (also deprecated; see notes above).
+  /// @deprecated Use setAttribute() instead.
   [[deprecated("Participant::set_attribute is deprecated; use LocalParticipant::setAttributes instead")]]
   void set_attribute(const std::string& key, const std::string& value) {
     attributes_[key] = value;
   }
 
-  // Deprecated - see removeAttribute() (also deprecated; see notes above).
+  /// @deprecated Use removeAttribute() instead.
   [[deprecated("Participant::remove_attribute is deprecated; use LocalParticipant::setAttributes instead")]]
   void remove_attribute(const std::string& key) {
     attributes_.erase(key);
   }
 
-  // Deprecated - see setKind() (also deprecated; see notes above).
+  /// @deprecated Kind is server-determined and not user-settable; this mutator will be removed.
   [[deprecated("Participant::set_kind is deprecated; Kind is server-determined and not user-settable")]]
   void set_kind(ParticipantKind kind) noexcept {
     kind_ = kind;
   }
 
-  // Deprecated - see setDisconnectReason() (also deprecated; see notes above).
+  /// @deprecated DisconnectReason is server-determined and not user-settable; this mutator will be removed.
   [[deprecated(
       "Participant::set_disconnect_reason is deprecated; DisconnectReason is server-determined and not "
       "user-settable")]]

include/livekit/remote_audio_track.h

@@ -53,7 +53,7 @@ class LIVEKIT_API RemoteAudioTrack : public Track {
   /// including its SID and name. Useful for debugging and logging.
   std::string toString() const;
 
-  // Deprecated - see toString()
+  /// @deprecated Use toString() instead.
   // NOLINTBEGIN(readability-identifier-naming)
   [[deprecated("RemoteAudioTrack::to_string is deprecated; use RemoteAudioTrack::toString instead")]]
   std::string to_string() const;

include/livekit/remote_participant.h

@@ -43,7 +43,7 @@ class LIVEKIT_API RemoteParticipant : public Participant {
 
   std::string toString() const;
 
-  // Deprecated - see toString()
+  /// @deprecated Use toString() instead.
   // NOLINTBEGIN(readability-identifier-naming)
   [[deprecated("RemoteParticipant::to_string is deprecated; use RemoteParticipant::toString instead")]]
   std::string to_string() const;

include/livekit/remote_video_track.h

@@ -53,7 +53,7 @@ class LIVEKIT_API RemoteVideoTrack : public Track {
   /// including its SID and name. Useful for debugging and logging.
   std::string toString() const;
 
-  // Deprecated - see toString()
+  /// @deprecated Use toString() instead.
   // NOLINTBEGIN(readability-identifier-naming)
   [[deprecated("RemoteVideoTrack::to_string is deprecated; use RemoteVideoTrack::toString instead")]]
   std::string to_string() const;

include/livekit/result.h

@@ -60,7 +60,7 @@ class [[nodiscard]] Result {
   /// Allows `if (result)` style success checks.
   explicit operator bool() const noexcept { return ok(); }
 
-  // Deprecated - see hasError()
+  /// @deprecated Use hasError() instead.
   // NOLINTBEGIN(readability-identifier-naming)
   [[deprecated("Result::has_error is deprecated; use Result::hasError instead")]]
   bool has_error() const noexcept {