From 904ac21020c1b178940abea70306988e543db60b Mon Sep 17 00:00:00 2001
From: raghavanone <115454562+raghavanone@users.noreply.github.com>
Date: Thu, 17 Nov 2022 20:11:11 +0530
Subject: [PATCH] Add docstrings for canine model (#19457)

* Add docstrings for canine model

* Update CanineForTokenClassification

Co-authored-by: ydshieh <ydshieh@users.noreply.github.com>
---
 .../models/canine/modeling_canine.py          | 57 +++++++++++++++----
 utils/documentation_tests.txt                 |  1 +
 2 files changed, 48 insertions(+), 10 deletions(-)

diff --git a/src/transformers/models/canine/modeling_canine.py b/src/transformers/models/canine/modeling_canine.py
index f05ba62c05..39ab584342 100644
--- a/src/transformers/models/canine/modeling_canine.py
+++ b/src/transformers/models/canine/modeling_canine.py
@@ -37,7 +37,13 @@ from ...modeling_outputs import (
 )
 from ...modeling_utils import PreTrainedModel
 from ...pytorch_utils import apply_chunking_to_forward, find_pruneable_heads_and_indices, prune_linear_layer
-from ...utils import add_code_sample_docstrings, add_start_docstrings, add_start_docstrings_to_model_forward, logging
+from ...utils import (
+    add_code_sample_docstrings,
+    add_start_docstrings,
+    add_start_docstrings_to_model_forward,
+    logging,
+    replace_return_docstrings,
+)
 from .configuration_canine import CanineConfig
 
 
@@ -1277,9 +1283,11 @@ class CanineForSequenceClassification(CaninePreTrainedModel):
     @add_start_docstrings_to_model_forward(CANINE_INPUTS_DOCSTRING.format("batch_size, sequence_length"))
     @add_code_sample_docstrings(
         processor_class=_TOKENIZER_FOR_DOC,
-        checkpoint=_CHECKPOINT_FOR_DOC,
+        checkpoint="vicl/canine-c-finetuned-cola",
         output_type=SequenceClassifierOutput,
         config_class=_CONFIG_FOR_DOC,
+        expected_output="'LABEL_0'",
+        expected_loss=0.82,
     )
     def forward(
         self,
@@ -1465,12 +1473,7 @@ class CanineForTokenClassification(CaninePreTrainedModel):
         self.post_init()
 
     @add_start_docstrings_to_model_forward(CANINE_INPUTS_DOCSTRING.format("batch_size, sequence_length"))
-    @add_code_sample_docstrings(
-        processor_class=_TOKENIZER_FOR_DOC,
-        checkpoint=_CHECKPOINT_FOR_DOC,
-        output_type=TokenClassifierOutput,
-        config_class=_CONFIG_FOR_DOC,
-    )
+    @replace_return_docstrings(output_type=TokenClassifierOutput, config_class=_CONFIG_FOR_DOC)
     def forward(
         self,
         input_ids: Optional[torch.LongTensor] = None,
@@ -1487,7 +1490,39 @@ class CanineForTokenClassification(CaninePreTrainedModel):
         r"""
         labels (`torch.LongTensor` of shape `(batch_size, sequence_length)`, *optional*):
             Labels for computing the token classification loss. Indices should be in `[0, ..., config.num_labels - 1]`.
-        """
+
+        Returns:
+
+        Example:
+
+        ```python
+        >>> from transformers import CanineTokenizer, CanineForTokenClassification
+        >>> import torch
+
+        >>> tokenizer = CanineTokenizer.from_pretrained("google/canine-s")
+        >>> model = CanineForTokenClassification.from_pretrained("google/canine-s")
+
+        >>> inputs = tokenizer(
+        ...     "HuggingFace is a company based in Paris and New York", add_special_tokens=False, return_tensors="pt"
+        ... )
+
+        >>> with torch.no_grad():
+        ...     logits = model(**inputs).logits
+
+        >>> predicted_token_class_ids = logits.argmax(-1)
+
+        >>> # Note that tokens are classified rather then input words which means that
+        >>> # there might be more predicted token classes than words.
+        >>> # Multiple token classes might account for the same word
+        >>> predicted_tokens_classes = [model.config.id2label[t.item()] for t in predicted_token_class_ids[0]]
+        >>> predicted_tokens_classes  # doctest: +SKIP
+        ```
+
+        ```python
+        >>> labels = predicted_token_class_ids
+        >>> loss = model(**inputs, labels=labels).loss
+        >>> round(loss.item(), 2)  # doctest: +SKIP
+        ```"""
         return_dict = return_dict if return_dict is not None else self.config.use_return_dict
 
         outputs = self.canine(
@@ -1545,9 +1580,11 @@ class CanineForQuestionAnswering(CaninePreTrainedModel):
     @add_start_docstrings_to_model_forward(CANINE_INPUTS_DOCSTRING.format("batch_size, sequence_length"))
     @add_code_sample_docstrings(
         processor_class=_TOKENIZER_FOR_DOC,
-        checkpoint=_CHECKPOINT_FOR_DOC,
+        checkpoint="Splend1dchan/canine-c-squad",
         output_type=QuestionAnsweringModelOutput,
         config_class=_CONFIG_FOR_DOC,
+        expected_output="'nice puppet'",
+        expected_loss=8.81,
     )
     def forward(
         self,
diff --git a/utils/documentation_tests.txt b/utils/documentation_tests.txt
index 200c836860..4bcfea5d71 100644
--- a/utils/documentation_tests.txt
+++ b/utils/documentation_tests.txt
@@ -36,6 +36,7 @@ src/transformers/models/blenderbot_small/modeling_blenderbot_small.py
 src/transformers/models/bloom/configuration_bloom.py
 src/transformers/models/camembert/configuration_camembert.py
 src/transformers/models/canine/configuration_canine.py
+src/transformers/models/canine/modeling_canine.py
 src/transformers/models/clip/configuration_clip.py
 src/transformers/models/clipseg/modeling_clipseg.py
 src/transformers/models/codegen/configuration_codegen.py