DOC: update the pandas.errors.DtypeWarning docstring

pandas/errors/__init__.py

@@ -38,9 +38,53 @@ class ParserError(ValueError):
 
 class DtypeWarning(Warning):
     """
-    Warning that is raised for a dtype incompatibility. This
-    can happen whenever `pd.read_csv` encounters non-
-    uniform dtypes in a column(s) of a given CSV file.
+    Warning raised when importing different dtypes in a column from a file.
+
+    Raised for a dtype incompatibility. This can happen whenever `pd.read_csv`
+    or `pd.read_table` encounter non-uniform dtypes in a column(s) of a given
+    CSV file.
+
+    It only happens when dealing with larger files.
+
+    See Also
+    --------
+    pd.read_csv : Read CSV (comma-separated) file into a DataFrame.
+    pd.read_table : Read general delimited file into a DataFrame.
+
+    Notes
+    -----
+    Despite the warning, the CSV file is imported with mixed types in a single
+    column. See the examples below to better understand this issue.
+
+    Examples
+    --------
+    This example creates and reads a large CSV file with a column that contains
+    `int` and `str`.
+
+    >>> df = pd.DataFrame({'a':['1']*100000 + ['X']*100000 + ['1']*100000,
+    ...                    'b':['b']*300000})
+    >>> df.to_csv('test', sep='\t', index=False, na_rep='NA')
+    >>> df2 = pd.read_csv('test', sep='\t')
+    Traceback (most recent call last):
+    ...
+    DtypeWarning: Columns (0) have mixed types...
+
+    Important to notice that df2 will contain both `str` and `int` for the
+    same input, '1'.
+
+    >>> df2.iloc[262140,0]
+    '1'
+    >>> type(df2.iloc[262140,0])
+    <class 'str'>
+    >>> df2.iloc[262150,0]
+    1
+    >>> type(df2.iloc[262150,0])
+    <class 'int'>
+
+    One way to solve this issue is using the parameter `converters` in the
+    `read_csv` and `read_table` functions to explicit the conversion:
+
+    >>> df2 = pd.read_csv('test', sep='\t', converters={'a': str})
     """