# Geração automática de docstrings

O decorador `@auto_docstring` gera docstrings consistentes para classes e métodos de modelos. Ele insere automaticamente as descrições padrão dos argumentos, de modo que você só precisa documentar argumentos novos ou personalizados. Ao [adicionar um novo modelo](./modular_transformers), pule o boilerplate e foque no que é novo.

## @auto_docstring

Importe o decorador no seu arquivo `modular_model.py` (ou `modeling_model.py` para modelos mais antigos).

```python
from ...utils import auto_docstring
```

Se o seu modelo herda de um modelo de outra biblioteca em um arquivo modular, `@auto_docstring` já é aplicado no pai. `make fix-repo` copia-o para o arquivo `modeling_model.py` gerado para você. Aplique o decorador explicitamente apenas para personalizar seu comportamento (modelos independentes, intros personalizados ou argumentos sobrescritos).

> [!WARNING]
> Ao sobrescrever qualquer decorador em um arquivo modular, inclua **todos** os decoradores da função ou classe pai. Se você sobrescrever apenas alguns, os demais não aparecerão no arquivo de modelagem gerado.

O decorador aceita os seguintes argumentos opcionais:

| argumento | descrição |
|---|---|
| `custom_intro` | Uma descrição da classe ou método, inserida antes da seção Args. Obrigatório para classes que não terminam com um [sufixo reconhecido](#how-it-works) como `ForCausalLM` ou `ForTokenClassification`. |
| `custom_args` | Texto de docstring para parâmetros específicos. Útil quando os mesmos argumentos personalizados aparecem em vários lugares no arquivo de modelagem. |
| `checkpoint` | Um identificador de checkpoint de modelo (`"org/my-model"`) usado para gerar exemplos de uso. Substitui o checkpoint inferido automaticamente a partir da classe de configuração. Geralmente definido em classes de configuração. |

## Uso

O funcionamento de `@auto_docstring` depende do que você está decorando. As classes de modelo obtêm a documentação dos parâmetros de `__init__`, as classes de configuração obtêm de anotações no nível da classe, as classes de processador geram automaticamente descrições a partir de seus componentes, e métodos como `forward` recebem tipos de retorno e exemplos de uso.

### Classes de modelo

Coloque `@auto_docstring` diretamente acima da definição da classe. O decorador deriva as descrições dos parâmetros a partir da assinatura e da docstring do método `__init__`.

```python
from transformers.modeling_utils import PreTrainedModel
from ...utils import auto_docstring

@auto_docstring
class MyAwesomeModel(PreTrainedModel):
    def __init__(self, config, custom_parameter: int = 10, another_custom_arg: str = "default"):
        r"""
        custom_parameter (`int`, *optional*, defaults to 10):
            Description of the custom_parameter for MyAwesomeModel.
        another_custom_arg (`str`, *optional*, defaults to "default"):
            Documentation for another unique argument.
        """
        super().__init__(config)
        self.custom_parameter = custom_parameter
        self.another_custom_arg = another_custom_arg
        # ... rest of your init

    # ... other methods
```

Passe `custom_intro` e `custom_args` para ter mais controle. Os argumentos personalizados podem estar em `custom_args` ou na docstring de `__init__`. Use `custom_args` quando os mesmos argumentos se repetem em vários métodos.

```python
@auto_docstring(
    custom_intro="""This model performs specific synergistic operations.
    It builds upon the standard Transformer architecture with unique modifications.""",
    custom_args="""
    custom_parameter (`type`, *optional*, defaults to `default_value`):
        A concise description for custom_parameter if not defined or overriding the description in `auto_docstring.py`.
    internal_helper_arg (`type`, *optional*, defaults to `default_value`):
        A concise description for internal_helper_arg if not defined or overriding the description in `auto_docstring.py`.
    """
)
class MySpecialModel(PreTrainedModel):
    def __init__(self, config: ConfigType, custom_parameter: "type" = "default_value", internal_helper_arg=None):
        # ...
```

Aplique também `@auto_docstring` a classes que herdam de [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput).

```python
@auto_docstring(
    custom_intro="""
    Custom model outputs with additional fields.
    """
)
@dataclass
class MyModelOutput(ImageClassifierOutput):
    r"""
    loss (`torch.Tensor`, *optional*):
        The loss of the model.
    custom_field (`torch.Tensor` of shape `(batch_size, hidden_size)`, *optional*):
        A custom output field specific to this model.
    """

    # Standard fields (hidden_states, logits, attentions, etc.) are documented automatically when
    # the description matches the standard text. Loss typically varies per model, so document it above.
    loss: Optional[torch.Tensor] = None
    logits: Optional[torch.Tensor] = None
    hidden_states: Optional[tuple[torch.Tensor, ...]] = None
    attentions: Optional[tuple[torch.Tensor, ...]] = None
    # Custom fields need to be documented in the docstring above
    custom_field: Optional[torch.Tensor] = None
```

### Classes de configuração

Coloque `@auto_docstring` diretamente acima de uma subclasse de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig), junto com o decorador `@strict`. `@strict` adiciona validação de tipos em tempo de execução e converte a classe em um dataclass validado. Os parâmetros de configuração são *anotações de nível de classe* (não argumentos de `__init__`), e `@auto_docstring` os lê do corpo da classe para gerar a documentação.

`ConfigArgs` fornece parâmetros padrão, como `vocab_size`, `hidden_size` e `num_hidden_layers`, de modo que eles não precisam de descrição, a menos que o comportamento seja diferente. Os parâmetros base de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) são excluídos automaticamente. O argumento `checkpoint` gera o exemplo de uso.

```python
from huggingface_hub.dataclasses import strict
from ...configuration_utils import PreTrainedConfig
from ...utils import auto_docstring

@strict
@auto_docstring(checkpoint="org/my-model-checkpoint")
class MyModelConfig(PreTrainedConfig):
    r"""
    custom_param (`int`, *optional*, defaults to 64):
        Description of a parameter specific to this model.
    another_param (`str`, *optional*, defaults to `"gelu"`):
        Description of another model-specific parameter.

    ```python
    from transformers import MyModelConfig, MyModel

    configuration = MyModelConfig()
    model = MyModel(configuration)
    configuration = model.config
    ```
    """

    model_type = "my_model"

    # Parâmetros padrão (vocab_size, hidden_size, etc.) são documentados automaticamente a partir de ConfigArgs. vocab_size: int = 32000 hidden_size: int = 768 num_hidden_layers: int = 12 # Parâmetros específicos do modelo devem ser documentados na docstring da classe acima. custom_param: int = 64 another_param: str = "gelu"
```

### Processor classes

Multimodal processors ([ProcessorMixin](/docs/transformers/main/pt/main_classes/processors#transformers.ProcessorMixin) subclasses, `processing_*.py`) always use the bare `@auto_docstring`. The class intro is auto-generated. Document only `__init__` parameters not already covered by `ProcessorArgs` (`image_processor`, `tokenizer`, `chat_template`, and others).

If every parameter is standard, omit the docstring. Decorate `__call__` with `@auto_docstring` too. Its body docstring holds only a `Returns:` section plus any extra model-specific call arguments. `return_tensors` is appended automatically.

```python
from ...processing_utils import ProcessorMixin, ProcessingKwargs, Unpack
from ...utils import auto_docstring

class MyModelProcessorKwargs(ProcessingKwargs, total=False):
    _defaults = {"text_kwargs": {"padding": False}}

@auto_docstring
class MyModelProcessor(ProcessorMixin):
    def __init__(self, image_processor=None, tokenizer=None, custom_param: int = 4, **kwargs):
        r"""
        custom_param (`int`, *optional*, defaults to 4):
            A parameter specific to this processor not covered by the standard ProcessorArgs.
        """
        super().__init__(image_processor, tokenizer)
        self.custom_param = custom_param

    @auto_docstring
    def __call__(self, images=None, text=None, **kwargs: Unpack[MyModelProcessorKwargs]):
        r"""
        Returns:
            [BatchFeature](/docs/transformers/main/pt/main_classes/feature_extractor#transformers.BatchFeature): A [BatchFeature](/docs/transformers/main/pt/main_classes/feature_extractor#transformers.BatchFeature) with the following fields:

            - **input_ids** -- Token ids to be fed to the model.
            - **pixel_values** -- Pixel values to be fed to the model.
        """
        # ...
```

#### Processadores de imagem e vídeo

Processadores de imagem e vídeo (subclasses de `BaseImageProcessor`, `image_processing_*.py`) seguem um de dois padrões.

Se o processador tiver parâmetros específicos do modelo, defina um TypedDict `XxxImageProcessorKwargs(ImagesKwargs, total=False)` com uma docstring para esses parâmetros, defina `valid_kwargs` na classe e use o `@auto_docstring` sem argumentos. O `__init__` não possui docstring.

```python
class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
    r"""
    custom_threshold (`float`, *optional*, defaults to `self.custom_threshold`):
        A parameter specific to this image processor.
    """
    custom_threshold: float | None

@auto_docstring
class MyModelImageProcessor(TorchvisionBackend):
    valid_kwargs = MyModelImageProcessorKwargs
    custom_threshold: float = 0.5

    def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
        super().__init__(**kwargs)
```

Se a classe apenas define atributos de nível de classe padrão (`size`, `resample`, `image_mean`, etc.) sem kwargs personalizados, use `@auto_docstring(custom_intro="Constructs a MyModel image processor.")` no lugar.

```python
@auto_docstring(custom_intro="Constructs a MyModel image processor.")
class MyModelImageProcessor(TorchvisionBackend):
    resample = PILImageResampling.BICUBIC
    image_mean = IMAGENET_STANDARD_MEAN
    image_std = IMAGENET_STANDARD_STD
    size = {"height": 224, "width": 224}
```

Ao sobrescrever `preprocess`, decore-o com `@auto_docstring` e documente apenas os argumentos que não estão em `ImageProcessorArgs`. Os argumentos padrão e `return_tensors` são incluídos automaticamente.

### Funções

Coloque `@auto_docstring` diretamente acima da definição da função. O decorador deriva as descrições dos parâmetros a partir da assinatura da função.

O decorador gera o texto do valor de retorno a partir da docstring da classe `ModelOutput`.

```python
class MyModel(PreTrainedModel):
    # ...
    @auto_docstring
    def forward(
        self,
        input_ids: Optional[torch.Tensor] = None,
        attention_mask: Optional[torch.Tensor] = None,
        new_custom_argument: Optional[torch.Tensor] = None,
        # ... other arguments
    ) -> Union[Tuple, ModelOutput]:
        r"""
        new_custom_argument (`torch.Tensor`, *optional*):
            Description of this new custom argument and its expected shape or type.
        """
        # ...
```

Passe `custom_intro` e `custom_args` para ter mais controle. Use `custom_args` para definir a documentação de argumentos compartilhados uma única vez quando os mesmos parâmetros aparecem em vários métodos.

```python
MODEL_COMMON_CUSTOM_ARGS = r"""
    common_arg_1 (`torch.Tensor`, *optional*, defaults to `default_value`):
        Description of common_arg_1
    common_arg_2 (`torch.Tensor`, *optional*, defaults to `default_value`):
        Description of common_arg_2
"""

class MyModel(PreTrainedModel):
    # ...
    @auto_docstring(
        custom_intro="""This is a custom introduction for the function.""",
        custom_args=MODEL_COMMON_CUSTOM_ARGS
    )
    def forward(self, input_ids=None, common_arg_1=None, common_arg_2=None) -> ModelOutput:
        r"""method-specific args go here"""
        # ...
```

Escreva as seções `Returns` e `Examples` manualmente no docstring para substituir as versões geradas automaticamente.

```python
    def forward(self, input_ids=None) -> torch.Tensor:
        r"""
        Returns:
            `torch.Tensor`: A custom Returns section for non-ModelOutput return types.

        Example:

        ```python
        model = MyModel.from_pretrained("org/my-model")
        output = model(input_ids)
        ```
        """
        # ...
```

### Documenting arguments

Follow these rules when documenting different argument types.

- `auto_docstring.py` defines standard arguments (`input_ids`, `attention_mask`, `pixel_values`, etc.) and includes them automatically. Don't redefine them locally unless the argument behaves differently in your model.

    If a standard argument behaves differently in your model, override it locally in a `r""" """` block. The local definition takes priority. The `labels` argument, for instance, is commonly customized per model and often needs an override.

- Standard config arguments (`vocab_size`, `hidden_size`, `num_hidden_layers`, etc.) follow the same principle but come from `ConfigArgs`. Standard processor arguments (`image_processor`, `tokenizer`, `do_resize`, `return_tensors`, etc.) come from `ProcessorArgs` and `ImageProcessorArgs`. Only document a parameter if it is model-specific or behaves differently from the standard description.

- Document new or custom arguments in an `r""" """` block. Place them after the signature for functions, in the `__init__` docstring for model or processor classes, in the class body docstring for config classes, or in the `XxxImageProcessorKwargs` TypedDict body for image processors.

    ```py
    argument_name (`type`, *optional*, defaults to `X`):
        Description of the argument.
        Explain its purpose, expected shape/type if complex, and default behavior.
        This can span multiple lines.
    ```

  * Inclua `type` entre crases.
  * Adicione *opcional* se o argumento não for obrigatório ou se tiver um valor padrão.
  * Adicione "padrão é X" se houver um valor padrão. Não é necessário adicionar "padrão é `None`" se o valor padrão for `None`.
  * Passe o mesmo bloco para `custom_args` quando os mesmos argumentos se repetirem em vários métodos (veja o [exemplo de funções acima](#functions)).

- O decorador extrai os tipos automaticamente das assinaturas de funções. Se um parâmetro tiver uma anotação de tipo, não é necessário repetir o tipo na string de formato da docstring. Quando ambos estão presentes, o tipo da assinatura tem precedência. O tipo da docstring atua como um recurso para parâmetros sem anotação.

## Verificando as docstrings

Um script de utilitário valida as docstrings quando você abre um pull request. O CI executa o script e verifica o seguinte.

> [!TIP]
> Se você vir um `[ERROR]` na saída, adicione a descrição do parâmetro ao docstring ou à classe Args apropriada em `auto_docstring.py`.

* Verifica se `@auto_docstring` é aplicado às classes de modelo e aos métodos públicos relevantes.
* Valida a completude e a consistência dos argumentos: os argumentos documentados devem existir na assinatura, e os tipos e valores padrão devem corresponder. Argumentos desconhecidos sem uma descrição local são sinalizados.
* Sinaliza placeholders incompletos, como `<fill_type>` e `<fill_docstring>`.
* Verifica se as docstrings seguem o estilo de formatação esperado.

Execute a verificação localmente antes de fazer o commit.

```bash
make fix-repo
```

`make fix-repo` também executa várias outras verificações. Para executar apenas as verificações de docstring e auto-docstring, use o comando abaixo.

```bash
# to only check files included in the diff without fixing them
python utils/check_docstrings.py
# to fix and overwrite the files in the diff
# python utils/check_docstrings.py --fix_and_overwrite
# to fix and overwrite all files
# python utils/check_docstrings.py --fix_and_overwrite --check_all
```

## Lista de verificação rápida

| Faça | Não |
|---|---|
| Aplique `@auto_docstring` às classes de modelo, configuração e processador e aos seus métodos principais (`forward`, `__call__`, `preprocess`). | Adicione `@auto_docstring` aos modelos herdados em arquivos modulares, pois ele é herdado automaticamente. |
| Documente apenas argumentos novos ou específicos do modelo. | Redefina os argumentos padrão (`input_ids`, `attention_mask`, `vocab_size`, etc.) que se comportam da mesma forma que suas descrições padrão. |
| Coloque os parâmetros de configuração na docstring do corpo da classe como anotações de nível de classe. | Coloque os parâmetros de configuração em `__init__`. |
| Coloque os parâmetros do processador de imagem em um TypedDict `XxxImageProcessorKwargs`. | Coloque os parâmetros do processador de imagem em `__init__`. |
| Execute `python utils/check_docstrings.py --fix_and_overwrite` antes de fazer o commit. | Ignore a saída `[ERROR]`, pois ela indica que um parâmetro não está documentado. |

## Como funciona

O decorador `@auto_docstring` gera docstrings por meio das seguintes etapas.

1. O decorador inspeciona a assinatura para ler argumentos, tipos e valores padrão do `__init__` da classe decorada ou da função decorada. Para classes de configuração, ele percorre as anotações de nível de classe ao longo da cadeia de herança e para antes de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig), excluindo os campos da classe base.

    Ele filtra automaticamente parâmetros como `self`, `kwargs`, `args`, `deprecated_arguments` e nomes com o prefixo `_`. Alguns parâmetros privados são renomeados para seus equivalentes públicos (`_out_features` → `out_features` para modelos de backbone).

2. As descrições comuns de argumentos vêm de `auto_docstring.py`: `ModelArgs` (entradas do modelo), `ModelOutputArgs` (campos de saída como `hidden_states`), `ImageProcessorArgs` (pré-processamento de imagens), `ProcessorArgs` (componentes do processador multimodal) e `ConfigArgs` (hiperparâmetros de configuração).

3. A descrição de cada parâmetro segue esta cadeia de prioridade:

    - Uma docstring manual (bloco `r""" """` ou `custom_args`) tem prioridade.
    - O dicionário de origem predefinido (`ModelArgs`, `ModelForArgs`, `ConfigArgs`, `ImageProcessorArgs`, `ProcessorArgs`, `ModelOutputArgs`) é o recurso de fallback.
    - Se nenhuma das fontes tiver uma descrição, o parâmetro é sinalizado com `[ERROR]` na saída de compilação.

4. Para classes de modelo com nomes padrão, como `ModelForCausalLM`, ou classes que mapeiam para um pipeline, `@auto_docstring` gera a introdução. Para processadores multimodais, a introdução lista quais componentes (tokenizer, image processor, etc.) a classe encapsula. Consulte [ClassDocstring](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/auto_docstring.py#L2437) para a lista completa.

    Se o nome da classe não estiver em `ClassDocstring`, defina `custom_intro`.

5. Docstrings predefinidas podem referenciar valores dinâmicos dos [auto_modules](https://github.com/huggingface/transformers/tree/main/src/transformers/models/auto) do Transformers, como `{processor_class}`, `{image_processor_class}` e `{config_class}`. Os placeholders são resolvidos automaticamente.

6. O decorador seleciona exemplos de uso com base na tarefa ou compatibilidade de pipeline do modelo. Ele lê os metadados do checkpoint da classe de configuração para que os exemplos utilizem IDs de modelo reais. O argumento `checkpoint` substitui o checkpoint inferido a partir da docstring da classe de configuração. Defina `checkpoint` nas classes de configuração, ou quando a inferência do checkpoint falhar. Se você vir um erro como `"Config not found for <model_name>"`, adicione uma entrada em `HARDCODED_CONFIG_FOR_MODELS` em `auto_docstring.py`.

7. Para métodos como `forward`, o decorador escreve a seção `Returns` a partir do tipo de retorno do método. Quando o tipo de retorno é uma subclasse de [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput), `@auto_docstring` extrai as descrições dos campos da docstring dessa classe. Um bloco `Returns` personalizado na docstring da função tem precedência.

8. Para os métodos em `UNROLL_KWARGS_METHODS` e as classes em `UNROLL_KWARGS_CLASSES`, o decorador expande `**kwargs` tipado com `Unpack[KwargsTypedDict]`. Cada chave do `TypedDict` se torna um parâmetro documentado.

    A mesma expansão se aplica aos métodos `__call__` e `preprocess` em subclasses de [BaseImageProcessor](/docs/transformers/main/pt/main_classes/image_processor#transformers.BaseImageProcessor) e [ProcessorMixin](/docs/transformers/main/pt/main_classes/processors#transformers.ProcessorMixin). Os tipos de base genéricos (`TextKwargs`, `ImagesKwargs`, `VideosKwargs`, `AudioKwargs`) são ignorados. Apenas subclasses específicas do modelo são expandidas.