[docs] Follow ups for consistent forward docstrings (#13779)

* feat: allow docstring checker to fix unused args in docstrings.

* feat: check for returns, too.

* [docs] add missing Returns sections to forward/__call__ docstrings (#13830)

Adds a Returns: section to the 43 model forward() and pipeline __call__()
methods flagged by utils/check_forward_call_docstrings.py, which requires a
Returns: section whenever the method has a non-None return annotation.

Descriptions reflect the actual return statements (Output dataclass when
return_dict=True, plain tuple otherwise; bare tensors / lists where
applicable) and reuse each file's existing doc-builder link form. Also
reformats a malformed single-line Returns: in pipeline_aura_flow.py that the
check could not detect.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Apply style fixes

---------

Co-authored-by: Steven Liu <59462357+stevhliu@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 4 people

src/diffusers/models/adapter.py

@@ -84,6 +84,11 @@ def forward(self, xs: torch.Tensor, adapter_weights: list[float] | None = None)
             adapter_weights (`list[float]`, *optional*, defaults to None):
                 A list of floats representing the weights which will be multiplied by each adapter's output before
                 summing them together. If `None`, equal weights will be used for all adapters.
+
+        Returns:
+            `list[torch.Tensor]`:
+                A list of feature tensors, one per scale, obtained by summing the per-scale features of each adapter
+                weighted by `adapter_weights`.
         """
         if adapter_weights is None:
             adapter_weights = torch.tensor([1 / self.num_adapter] * self.num_adapter)
@@ -273,6 +278,11 @@ def forward(self, x: torch.Tensor) -> list[torch.Tensor]:
         Args:
             x (`torch.Tensor`):
                 The input tensor to process through the adapter model.
+
+        Returns:
+            `list[torch.Tensor]`:
+                A list of feature tensors, each representing information extracted at a different scale from the input.
+                The length of the list equals the number of downsample blocks in the adapter.
         """
         return self.adapter(x)
 

src/diffusers/models/autoencoders/autoencoder_asym_kl.py

@@ -169,6 +169,10 @@ def forward(
             generator (`torch.Generator`, *optional*):
                 A [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) to make sampling
                 deterministic.
+
+        Returns:
+            [`DecoderOutput`] or `tuple`:
+                If `return_dict` is True, a [`DecoderOutput`] is returned, otherwise a plain `tuple` is returned.
         """
         x = sample
         posterior = self.encode(x).latent_dist

src/diffusers/models/autoencoders/autoencoder_dc.py

@@ -711,6 +711,11 @@ def forward(self, sample: torch.Tensor, return_dict: bool = True) -> torch.Tenso
             sample (`torch.Tensor`): Input sample.
             return_dict (`bool`, *optional*, defaults to `True`):
                 Whether or not to return a [`DecoderOutput`] instead of a plain tuple.
+
+        Returns:
+            [`~models.vae.DecoderOutput`] or `tuple`:
+                If `return_dict` is True, a [`~models.vae.DecoderOutput`] is returned, otherwise a plain `tuple` is
+                returned.
         """
         encoded = self.encode(sample, return_dict=False)[0]
         decoded = self.decode(encoded, return_dict=False)[0]

src/diffusers/models/autoencoders/autoencoder_kl.py

@@ -427,6 +427,11 @@ def forward(
             generator (`torch.Generator`, *optional*):
                 A [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) to make sampling
                 deterministic.
+
+        Returns:
+            [`~models.vae.DecoderOutput`] or `tuple`:
+                If `return_dict` is True, a [`~models.vae.DecoderOutput`] is returned, otherwise a plain `tuple` is
+                returned.
         """
         x = sample
         posterior = self.encode(x).latent_dist

src/diffusers/models/autoencoders/autoencoder_kl_allegro.py

@@ -1054,6 +1054,11 @@ def forward(
                 Whether or not to return a [`DecoderOutput`] instead of a plain tuple.
             generator (`torch.Generator`, *optional*):
                 PyTorch random number generator.
+
+        Returns:
+            [`~models.vae.DecoderOutput`] or `tuple`:
+                If `return_dict` is True, a [`~models.vae.DecoderOutput`] is returned, otherwise a plain `tuple` is
+                returned.
         """
         x = sample
         posterior = self.encode(x).latent_dist

src/diffusers/models/autoencoders/autoencoder_kl_cogvideox.py

@@ -1419,6 +1419,11 @@ def forward(
             generator (`torch.Generator`, *optional*):
                 A [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) to make sampling
                 deterministic.
+
+        Returns:
+            [`~models.vae.DecoderOutput`] or `tuple`:
+                If `return_dict` is True, a [`~models.vae.DecoderOutput`] is returned, otherwise a plain `tuple` is
+                returned.
         """
         x = sample
         posterior = self.encode(x).latent_dist

src/diffusers/models/autoencoders/autoencoder_kl_cosmos.py

@@ -1088,6 +1088,11 @@ def forward(
             generator (`torch.Generator`, *optional*):
                 A [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) to make sampling
                 deterministic.
+
+        Returns:
+            [`~models.vae.DecoderOutput`] or `tuple`:
+                If `return_dict` is True, a [`~models.vae.DecoderOutput`] is returned, otherwise a plain `tuple` is
+                returned.
         """
         x = sample
         posterior = self.encode(x).latent_dist

src/diffusers/models/autoencoders/autoencoder_kl_flux2.py

@@ -444,6 +444,11 @@ def forward(
             generator (`torch.Generator`, *optional*):
                 A [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) to make sampling
                 deterministic.
+
+        Returns:
+            [`~models.vae.DecoderOutput`] or `tuple`:
+                If `return_dict` is True, a [`~models.vae.DecoderOutput`] is returned, otherwise a plain `tuple` is
+                returned.
         """
         x = sample
         posterior = self.encode(x).latent_dist

src/diffusers/models/autoencoders/autoencoder_kl_hunyuan_video.py

@@ -1064,6 +1064,11 @@ def forward(
             generator (`torch.Generator`, *optional*):
                 A [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) to make sampling
                 deterministic.
+
+        Returns:
+            [`~models.vae.DecoderOutput`] or `tuple`:
+                If `return_dict` is True, a [`~models.vae.DecoderOutput`] is returned, otherwise a plain `tuple` is
+                returned.
         """
         x = sample
         posterior = self.encode(x).latent_dist

src/diffusers/models/autoencoders/autoencoder_kl_hunyuanimage.py

@@ -681,6 +681,11 @@ def forward(
             generator (`torch.Generator`, *optional*):
                 A [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) to make sampling
                 deterministic.
+
+        Returns:
+            [`~models.vae.DecoderOutput`] or `tuple`:
+                If `return_dict` is True, a [`~models.vae.DecoderOutput`] is returned, otherwise a plain `tuple` is
+                returned.
         """
         posterior = self.encode(sample).latent_dist
         if sample_posterior: