title: How to docstring kwargs and their expected types
body: <p>What is the conventional way to express in a docstring the expected types of keyword arguments?</p>
  
  <p>Or is this out of principle something I should not be doing at all? Google is suspiciously un-forthcoming on the subject.</p>
  
  <p>(I am interested in doing this because I find that keeping track of expected types of all variables is very helpful as I code. I use PyCharm, which warns me when arguments have unexpected types, or when custom class attributes may be unresolved etc.)</p>
  
  <p>However, I am finding that sometimes the list of possible keywrord arguments listed as</p>
  
  <pre><code>def foo(bar, parameter_1: int=1, paramter_2: str='', ...etc )
  </code></pre>
  
  <p>can become long and unreadable..</p>
  
  <p>Consider the following code</p>
  
  <pre><code>class Person:
      def __init__(self, id: int, **kwargs):
          """
          :param id: social security number
          :type id: int
          :param **name: person's first name
          :type **name: str
          :param **age: person's age in years, rounded down
          :type **age: int
          """
          self.data = kwargs
  
  
  bob = Person(123456568, name='Bob', age=48)
  sally = Person(1245654568, name='Sally', age='22')
  </code></pre>
  
  <p>I would like to use the docstring to state the expected types. And I would like PyCharm to warn me that sally's age has the wrong type. Of course, I don't know if PyCharm even has the capacity to 'understand' that level of detail in the docstring. Nevertheless I'd like to know what the conventional way to do it is.</p>
  
  <p>Other comments and suggestions about kwargs and docstrings also welcome.</p>