Consider __doc__ always Optional. (#641)

python/mypy#2380 showed a discrepancy between object and FunctionType in stdlib2. The first defined __doc__ to be str, the second Optional[str]. As FunctionType depends on object, this is no longer valid.

As suggested by @gvanrossum in python/mypy#2380, all __doc__ should be considered Optional.

(Final verdict was just to remove most __doc__ attributes since it's inherited from object.)

stdlib/2/__builtin__.pyi

@@ -27,7 +27,7 @@ class staticmethod: pass   # Special, only valid as a decorator.
 class classmethod: pass  # Special, only valid as a decorator.
 
 class object:
-    __doc__ = ...  # type: str
+    __doc__ = ...  # type: Optional[str]
     __class__ = ...  # type: type
 
     def __init__(self) -> None: ...

stdlib/2/abc.pyi

@@ -12,7 +12,6 @@ def abstractmethod(funcobj: Any) -> Any: ...
 class ABCMeta(type):
     # TODO: FrozenSet
     __abstractmethods__ = ...  # type: Set[Any]
-    __doc__ = ...  # type: str
     _abc_cache = ...  # type: _weakrefset.WeakSet
     _abc_invalidation_counter = ...  # type: int
     _abc_negative_cache = ...  # type: _weakrefset.WeakSet
@@ -31,7 +30,6 @@ class _C:
 # TODO: The real abc.abstractproperty inherits from "property".
 class abstractproperty(object):
     def __new__(cls, func: Any) -> Any: ...
-    __doc__ = ...  # type: str
     __isabstractmethod__ = ...  # type: bool
     doc = ...  # type: Any
     fdel = ...  # type: Any

stdlib/2/ast.pyi

@@ -33,12 +33,10 @@ def literal_eval(node_or_string: Union[str, AST]) -> Any: ...
 def walk(node: AST) -> Iterator[AST]: ...
 
 class NodeVisitor():
-    __doc__ = ...  # type: str
     def visit(self, node: AST) -> Any: ...
     def generic_visit(self, node: AST) -> None: ...
 
 class NodeTransformer(NodeVisitor):
-    __doc__ = ...  # type: str
     def generic_visit(self, node: AST) -> None: ...
 
 

stdlib/2/optparse.pyi

@@ -18,7 +18,6 @@ class OptParseError(Exception):
     def __init__(self, msg) -> None: ...
 
 class BadOptionError(OptParseError):
-    __doc__ = ...  # type: str
     opt_str = ...  # type: Any
     def __init__(self, opt_str) -> None: ...
 
@@ -65,7 +64,6 @@ class HelpFormatter:
     def store_option_strings(self, parser) -> None: ...
 
 class IndentedHelpFormatter(HelpFormatter):
-    __doc__ = ...  # type: str
     _long_opt_fmt = ...  # type: str
     _short_opt_fmt = ...  # type: str
     current_indent = ...  # type: int
@@ -93,7 +91,6 @@ class Option:
     TYPED_ACTIONS = ...  # type: Tuple[str, ...]
     TYPES = ...  # type: Tuple[str, ...]
     TYPE_CHECKER = ...  # type: Dict[str, Callable]
-    __doc__ = ...  # type: str
     _long_opts = ...  # type: List[Text]
     _short_opts = ...  # type: List[Text]
     action = ...  # type: str
@@ -162,7 +159,6 @@ class OptionGroup(OptionContainer):
     def set_title(self, title) -> None: ...
 
 class OptionParser(OptionContainer):
-    __doc__ = ...  # type: str
     _long_opt = ...  # type: Dict[Text, Any]
     _short_opt = ...  # type: Dict[Any, Any]
     allow_interspersed_args = ...  # type: bool
@@ -220,11 +216,9 @@ class OptionParser(OptionContainer):
     def set_usage(self, usage: Text) -> None: ...
 
 class OptionValueError(OptParseError):
-    __doc__ = ...  # type: str
     msg = ...  # type: Any
 
 class TitledHelpFormatter(HelpFormatter):
-    __doc__ = ...  # type: str
     _long_opt_fmt = ...  # type: str
     _short_opt_fmt = ...  # type: str
     current_indent = ...  # type: int

stdlib/2/tempfile.pyi

@@ -19,7 +19,6 @@ template = ...  # type: str
 _name_sequence = ...  # type: Optional[_RandomNameSequence]
 
 class _RandomNameSequence:
-    __doc__ = ...  # type: str
     _rng = ...  # type: random.Random
     _rng_pid = ...  # type: int
     characters = ...  # type: str
@@ -31,7 +30,6 @@ class _RandomNameSequence:
     def normcase(path: AnyStr) -> AnyStr: ...
 
 class _TemporaryFileWrapper(IO[str]):
-    __doc__ = ...  # type: str
     close_called = ...  # type: bool
     delete = ...  # type: bool
     file = ...  # type: IO

stdlib/2/types.pyi

@@ -40,7 +40,6 @@ class FunctionType:
     __code__ = func_code
     __defaults__ = func_defaults
     __dict__ = func_dict
-    __doc__ = func_doc
     __globals__ = func_globals
     __name__ = func_name
     def __call__(self, *args: Any, **kwargs: Any) -> Any: ...