Incorrect docs and unclear behaviour of `torch.multinomial`

Hi! Let’s have a look at the docs:

First of all, let’s try to reproduce the example:

>>> import torch
>>> weights = torch.tensor([0, 10, 3, 0], dtype=torch.float)
>>> torch.multinomial(weights, 4)
RuntimeError                              Traceback (most recent call last)
<ipython-input-3-6a53ba27a4e6> in <module>
----> 1 torch.multinomial(weights, 4)
RuntimeError: invalid argument 2: invalid multinomial distribution (with replacement=False, not enough non-negative category to sample) at /pytorch/aten/src/TH/generic/THTensorRandom.cpp:320
  1. I suppose what is meant by error is “not enough positive category”. Otherwise, it is strange to get 0 in the output if the probability of this element is 0.0. I firstly thought that it is because replacement=False, but there is one more 0 in the output which makes the example even more confusing.
  2. Here it is said that under the hood the function is equivalent to torch.distributions.Categorical. The distribution, however, can be parametrized with either probs or logits. How exactly the input argument of torch.multinomial is treated?

PyTorch’s version: 1.0.1.post2