generate() - documentation of `length_penalty' is misleading (and actually wrong) 
Author: nitaytech
Pull request: no
Labels: name: bug

### System Info

- `transformers` version: 4.20.1
- Platform: Linux-5.15.0-1014-azure-x86_64-with-glibc2.31
- Python version: 3.10.4
- Huggingface_hub version: 0.8.1
- PyTorch version (GPU?): 1.12.0 (True)
- Tensorflow version (GPU?): not installed (NA)
- Flax version (CPU?/GPU?/TPU?): not installed (NA)
- Jax version: not installed
- JaxLib version: not installed
- Using GPU in script?: <fill in>
- Using distributed or parallel set-up in script?: <fill in>


### Who can help?

@patrickvonplaten @Narsil  @gante

### Information

- [X] The official example scripts
- [ ] My own modified scripts

### Tasks

- [ ] An officially supported task in the `examples` folder (such as GLUE/SQuAD, ...)
- [ ] My own task or dataset (give details below)

### Reproduction

----

### Expected behavior

According to the documentation of the `generate()` function (transformers/generation_utils.py), the description of the `length_penalty` is as dollows:

>             length_penalty (`float`, *optional*, defaults to 1.0):
>                  Exponential penalty to the length. 1.0 means that the beam score is penalized by the sequence length.
>                  0.0 means no penalty. Set to values < 0.0 in order to encourage the model to generate longer
>                  sequences, to a value > 0.0 in order to encourage the model to produce shorter sequences.

However, this documentation is not aligned with the implementation of the `length_penalty` in methods which use it (like, `BeamHypotheses.add()`) or with the documentation of these methods:

Implementation:

`score = sum_logprobs / (hyp.shape[-1] ** self.length_penalty)`
**Note: the sum_logprobs is NEGATIVE(!!!), thus dividing it by a larger number making the score bigger**.

Documentation:

> length_penalty (`float`, *optional*, defaults to 1.0):
>             Exponential penalty to the length. 1.0 means no penalty. Set to values < 1.0 in order to encourage the
>             model to generate shorter sequences, to a value > 1.0 in order to encourage the model to produce longer
>             sequences.


I think the documentation of `BeamHypotheses.add()` is more correct and less misleading. I do understand that the sum_logprobs is the right logprob that represents the sequence logprobs, however, since the common practice for generation is to use the *mean* logprob: ` sum_logprobs / hyp.shape[-1]`, writing "1.0 means that the beam score is penalized by the sequence length" is misleading. Moreover, "Set to values < 0.0 in order to encourage the model to generate longer sequences, to a value > 0.0 in order to encourage the model to produce shorter sequences." is just not correct, since the sum_logprobs is NEGATIVE(!!!), thus dividing it by a larger number making the score bigger (bigger length_penalty --> bigger denominator --> bigger (negative) score (closer to zero). The documentation should be changed or explained more carefully (and be aligned with the implementations). 

I would change the documentation to something like:

> length_penalty (`float`, *optional*, defaults to 1.0):
>             Exponential penalty to the length. **0.0 means no penalty. 1.0 means the score of each sequence is the
>             log probability divided by the sequence length (the mean log probability, which is the common practice).**
>             Set to values < 1.0 in order to encourage the model to generate shorter sequences,
>             to a value > 1.0 in order to encourage the model to produce longer sequences.

Thanks

Comments:
Hi @nitaytech 👋 we are aware of this issue, it is also being tracked here -- https://github.com/huggingface/transformers/issues/18208