Refresh the docs a bit in preparation for the release

4 files changed, 243 insertions, 226 deletions

diff --git a/ChangeLog b/ChangeLog
index 81750fae0..0b5ad6f2b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -41,7 +41,7 @@ Release date: TBA
 
 * ``function-redefined`` exempts function redefined on a condition.
 
-   Close #2410
+  Close #2410
 
 * ``typing.overload`` functions are exempted from docstring checks
 
@@ -98,11 +98,11 @@ Release date: TBA
 
 * ``missing-*-docstring`` can look for ``__doc__`` assignments.
 
-   Close #3301
+  Close #3301
 
 * ``undefined-variable`` can now find undefined loop iterables
 
-   Close #498
+  Close #498
 
 * ``safe_infer`` can infer a value as long as all the paths share the same type.
 
diff --git a/doc/whatsnew/2.5.rst b/doc/whatsnew/2.5.rst
index 3fb98236d..aa48b615f 100644
--- a/doc/whatsnew/2.5.rst
+++ b/doc/whatsnew/2.5.rst
@@ -13,23 +13,23 @@ Summary -- Release highlights
 New checkers
 ============
 
-* A new check ``isinstance-second-argument-not-valid-type``` was added.
+* A new check ``isinstance-second-argument-not-valid-type`` was added.
 
-  This check is emitted whenever **pylint** finds a call to the `isinstance`
-  function with a second argument that is not a type. Such code is likely
-  unintended as it will cause a TypeError to be thrown at runtime error.
+   This check is emitted whenever **pylint** finds a call to the `isinstance`
+   function with a second argument that is not a type. Such code is likely
+   unintended as it will cause a TypeError to be thrown at runtime error.
 
 * A new check ``assert-on-string-literal`` was added.
 
-  This check is emitted whenever **pylint** finds an assert statement
-  with a string literal as its first argument. Such assert statements
-  are probably unintended as they will always pass.
+   This check is emitted whenever **pylint** finds an assert statement
+   with a string literal as its first argument. Such assert statements
+   are probably unintended as they will always pass.
 
 * A new check ``f-string-without-interpolation`` was added.
 
-  This check is emitted whenever **pylint** detects the use of an
-  f-string without having any interpolated values in it, which means
-  that the f-string can be a normal string.
+   This check is emitted whenever **pylint** detects the use of an
+   f-string without having any interpolated values in it, which means
+   that the f-string can be a normal string.
 
 * Multiple checks for invalid return types of protocol functions were added:
 
@@ -46,51 +46,45 @@ New checkers
 
 * A new check ``inconsistent-quotes`` was added.
 
-  This check is emitted when quotes delimiters (" and ') are not used
-  consistently throughout a module.  It makes allowances for avoiding
-  unnecessary escaping, allowing, for example, ``"Don't error"`` in a module in
-  which single-quotes otherwise delimit strings so that the single quote in
-  ``Don't`` doesn't need to be escaped.
+   This check is emitted when quotes delimiters (``"`` and ``'``) are not used
+   consistently throughout a module.  It allows avoiding unnecessary escaping,
+   allowing, for example, ``"Don't error"`` in a module in which single-quotes
+   otherwise delimit strings so that the single quote in ``Don't`` doesn't need to be escaped.
+
+* A new check ``non-str-assignment-to-dunder-name`` was added to ensure that only strings are assigned to ``__name__`` attributes.
 
 
 Other Changes
 =============
 
-* Don't emit ``line-too-long`` for multilines when a
-  `pylint:disable=line-too-long` comment stands at their end.
+* Configuration can be read from a setup.cfg or pyproject.toml file in the current directory.
+  A setup.cfg must prepend pylintrc section names with ``pylint.``, for example ``[pylint.MESSAGES CONTROL]``.
+  A pyproject.toml file must prepend section names with ``tool.pylint.``, for example ``[tool.pylint.'MESSAGES CONTROL']``.
+  These files can also be passed in on the command line.
 
-  For example the following code will not trigger any ``line-too-long`` message::
+* Add new ``good-names-rgx`` and ``bad-names-rgx`` to enable permitting or disallowing of names via regular expressions
 
-    def example():
-      """
-      This is a very very very long line within a docstring that should trigger a pylint C0301 error line-too-long
+  To enable better handling of whitelisting/blacklisting names, we added two new config options: good-names-rgxs: a comma-
+  separated list of regexes, that if a name matches will be exempt of naming-checking. bad-names-rgxs: a comma-
+  separated list of regexes, that if a name matches will be always marked as a blacklisted name.
 
-      Even spread on multiple lines, the disable command is still effective on very very very, maybe too much long docstring
-      """#pylint: disable=line-too-long
-    pass
+* Mutable ``collections.*`` are now flagged as dangerous defaults.
 
-* Configuration can be read from a setup.cfg or pyproject.toml file
-  in the current directory.
-  A setup.cfg must prepend pylintrc section names with ``pylint.``,
-  for example ``[pylint.MESSAGES CONTROL]``.
-  A pyproject.toml file must prepend section names with ``tool.pylint.``,
-  for example ``[tool.pylint.'MESSAGES CONTROL']``.
-  These files can also be passed in on the command line.
+* Add new ``--fail-under`` flag for setting the threshold for the score to fail overall tests. If the score is over the fail-under threshold, pylint will complete SystemExit with value 0 to indicate no errors.
 
-* Add new good-names-rgx and bad-names-rgx to enable white-/blacklisting of regular expressions
+* Added a new option ``notes-rgx`` to make fixme warnings more flexible. Now either ``notes`` or ``notes-rgx`` option can be used to detect fixme warnings.
 
-To enable better handling of whitelisting/blacklisting names, we added two new config options: good-names-rgxs: a comma-
-separated list of regexes, that if a name matches will be exempt of naming-checking. bad-names-rgxs: a comma-
-separated list of regexes, that if a name matches will be always marked as a blacklisted name.
+* Non-ASCII characters are now allowed by ``invalid-name``.
 
-* Mutable ``collections.*`` are now flagged as dangerous defaults.
+* ``pylint`` no longer emits ``invalid-name`` for non-constants found at module level.
 
-* Add new --fail-under flag for setting the threshold for the score to fail overall tests. If the score is over the fail-under threshold, pylint will complete SystemExit with value 0 to indicate no errors.
+  Pylint was considering all module level variables as constants, which is not what PEP 8 is actually mandating.
 
-* Add a new check (non-str-assignment-to-dunder-name) to ensure that only strings are assigned to ``__name__`` attributes
+* A new check ``non-ascii-name`` was added to detect identifiers with non-ASCII characters.
 
-* Add a new option ``notes-rgx`` to make fixme warnings more flexible. Now either ``notes`` or ``notes-rgx`` option can be used to detect fixme warnings.
+* Overloaded typing functions no longer trigger ``no-self-use``, ``unused-argument``, ``missing-docstring`` and similar checks
+  that assumed that overloaded functions are normal functions.
 
-* Non-ASCII characters are now allowed by ``invalid-name``.
+* ``python -m pylint`` can no longer be made to import files from the local directory.
 
-* Add a new check ``non-ascii-name`` to detect identifiers with non-ASCII characters.
+* Various false positives have been fixed which you can read more about in the Changelog files.
diff --git a/examples/pylintrc b/examples/pylintrc
index 7196a8203..f6aad454e 100644
--- a/examples/pylintrc
+++ b/examples/pylintrc
@@ -5,6 +5,9 @@
 # run arbitrary code.
 extension-pkg-whitelist=
 
+# Specify a score threshold to be exceeded before program exits with error.
+fail-under=10
+
 # Add files or directories to the blacklist. They should be base names, not
 # paths.
 ignore=CVS
@@ -33,9 +36,6 @@ load-plugins=
 # Pickle collected data for later comparisons.
 persistent=yes
 
-# Specify a configuration file.
-#rcfile=
-
 # When enabled, pylint would attempt to guess common misconfiguration and emit
 # user-friendly hints instead of false-positive error messages.
 suggestion-mode=yes
@@ -184,6 +184,48 @@ max-nested-blocks=5
 never-returning-functions=sys.exit
 
 
+[LOGGING]
+
+# Format style used to check logging format string. `old` means using %
+# formatting, `new` is for `{}` formatting,and `fstr` is for f-strings.
+logging-format-style=old
+
+# Logging modules to check that the string format arguments are in logging
+# function parameter format.
+logging-modules=logging
+
+
+[SPELLING]
+
+# Limits count of emitted suggestions for spelling mistakes.
+max-spelling-suggestions=4
+
+# Spelling dictionary name. Available dictionaries: none. To make it work,
+# install the python-enchant package.
+spelling-dict=
+
+# List of comma separated words that should not be checked.
+spelling-ignore-words=
+
+# A path to a file that contains the private dictionary; one word per line.
+spelling-private-dict-file=
+
+# Tells whether to store unknown words to the private dictionary (see the
+# --spelling-private-dict-file option) instead of raising a message.
+spelling-store-unknown-words=no
+
+
+[MISCELLANEOUS]
+
+# List of note tags to take in consideration, separated by a comma.
+notes=FIXME,
+      XXX,
+      TODO
+
+# Regular expression of note tags to take in consideration.
+#notes-rgx=
+
+
 [TYPECHECK]
 
 # List of decorators that produce context managers, such as
@@ -239,32 +281,6 @@ missing-member-max-choices=1
 signature-mutators=
 
 
-[LOGGING]
-
-# Format style used to check logging format string. `old` means using %
-# formatting, `new` is for `{}` formatting, and `fstr` is for f-strings.
-logging-format-style=old
-
-# Logging modules to check that the string format arguments are in logging
-# function parameter format.
-logging-modules=logging
-
-
-[SIMILARITIES]
-
-# Ignore comments when computing similarities.
-ignore-comments=yes
-
-# Ignore docstrings when computing similarities.
-ignore-docstrings=yes
-
-# Ignore imports when computing similarities.
-ignore-imports=no
-
-# Minimum lines number of a similarity.
-min-similarity-lines=4
-
-
 [VARIABLES]
 
 # List of additional names supposed to be defined in builtins. Remember that
@@ -295,26 +311,6 @@ init-import=no
 redefining-builtins-modules=six.moves,past.builtins,future.builtins,builtins,io
 
 
-[SPELLING]
-
-# Limits count of emitted suggestions for spelling mistakes.
-max-spelling-suggestions=4
-
-# Spelling dictionary name. Available dictionaries: none. To make it work,
-# install the python-enchant package.
-spelling-dict=
-
-# List of comma separated words that should not be checked.
-spelling-ignore-words=
-
-# A path to a file that contains the private dictionary; one word per line.
-spelling-private-dict-file=
-
-# Tells whether to store unknown words to the private dictionary (see the
-# --spelling-private-dict-file option) instead of raising a message.
-spelling-store-unknown-words=no
-
-
 [FORMAT]
 
 # Expected format of line ending, e.g. empty (any line ending), LF or CRLF.
@@ -352,6 +348,21 @@ single-line-class-stmt=no
 single-line-if-stmt=no
 
 
+[SIMILARITIES]
+
+# Ignore comments when computing similarities.
+ignore-comments=yes
+
+# Ignore docstrings when computing similarities.
+ignore-docstrings=yes
+
+# Ignore imports when computing similarities.
+ignore-imports=no
+
+# Minimum lines number of a similarity.
+min-similarity-lines=4
+
+
 [BASIC]
 
 # Naming style matching correct argument names.
@@ -376,6 +387,10 @@ bad-names=foo,
           tutu,
           tata
 
+# Bad variable names regexes, separated by a comma. If names match any regex,
+# they will always be refused
+bad-names-rgxs=
+
 # Naming style matching correct class attribute names.
 class-attribute-naming-style=any
 
@@ -416,6 +431,10 @@ good-names=i,
            Run,
            _
 
+# Good variable names regexes, separated by a comma. If names match any regex,
+# they will always be accepted
+good-names-rgxs=
+
 # Include a hint for the correct naming format with invalid-name.
 include-naming-hint=no
 
@@ -461,30 +480,23 @@ variable-naming-style=snake_case
 #variable-rgx=
 
 
-[MISCELLANEOUS]
-
-# List of note tags to take in consideration, separated by a comma.
-notes=FIXME,
-      XXX,
-      TODO
-
-# Regular expressio of note tags to take in consideration.
-notes-rgx=a^
-
 [STRING]
 
-# This flag controls whether the implicit-str-concat-in-sequence should
-# generate a warning on implicit string concatenation in sequences defined over
-# several lines.
-check-str-concat-over-line-jumps=no
-
 # This flag controls whether inconsistent-quotes generates a warning when the
 # character used as a quote delimiter is used inconsistently within a module.
 check-quote-consistency=no
 
+# This flag controls whether the implicit-str-concat should generate a warning
+# on implicit string concatenation in sequences defined over several lines.
+check-str-concat-over-line-jumps=no
+
 
 [IMPORTS]
 
+# List of modules that can be imported at any level, not just the top level
+# one.
+allow-any-import-level=
+
 # Allow wildcard imports from modules that define __all__.
 allow-wildcard-with-all=no
 
diff --git a/man/pylint.1 b/man/pylint.1
index 56d5ec3e8..7e0e4e94c 100644
--- a/man/pylint.1
+++ b/man/pylint.1
@@ -1,4 +1,4 @@
-.TH pylint 1 "2019-06-29" pylint
+.TH pylint 1 "2020-03-13" pylint
 .SH NAME
 .B pylint
 \- python code static checker
@@ -38,8 +38,6 @@ show this help message and exit
 more verbose help.
 
 .SH MASTER
-.IP "--rcfile=<file>"
-Specify a configuration file.
 .IP "--init-hook=<code>"
 Python code to execute, usually for sys.path manipulation such as pygtk.require().
 .IP "--errors-only, -E"
@@ -56,6 +54,8 @@ Add files or directories matching the regex patterns to the blacklist. The regex
 Pickle collected data for later comparisons. [default: yes]
 .IP "--load-plugins=<modules>"
 List of plugins (as comma separated values of python module names) to load, usually to register additional checkers. [default: none]
+.IP "--fail-under=<score>"
+Specify a score threshold to be exceeded before program exits with error. [default: 10]
 .IP "--jobs=<n-processes>, -j <n-processes>"
 Use multiple processes to speed up Pylint. Specifying 0 will auto-detect the number of processors available to use. [default: 1]
 .IP "--limit-inference-results=<number-of-results>"
@@ -70,10 +70,14 @@ Always return a 0 (non-error) status code, even if lint errors are found. This i
 Interpret the stdin as a python script, whose filename needs to be passed as the module_or_package argument.
 
 .SH COMMANDS
+.IP "--rcfile=<file>"
+Specify a configuration file to load.
 .IP "--help-msg=<msg-id>"
 Display a help message for the given message id and exit. The value may be a comma separated list of message ids.
 .IP "--list-msgs"
 Generate pylint's messages.
+.IP "--list-msgs-enabled"
+Display a list of what messages are enabled and disabled with the given configuration.
 .IP "--list-groups"
 List pylint's message groups.
 .IP "--list-conf-levels"
@@ -103,6 +107,30 @@ Activate the evaluation score. [default: yes]
 .IP "--msg-template=<template>"
 Template used to display messages. This is a python new-style format string used to format the message information. See doc for all details.
 
+.SH LOGGING
+.IP "--logging-modules=<comma separated list>"
+Logging modules to check that the string format arguments are in logging function parameter format. [default: logging]
+.IP "--logging-format-style=<old (%) or new ({) or fstr (f'')>"
+Format style used to check logging format string. `old` means using % formatting, `new` is for `{}` formatting,and `fstr` is for f-strings. [default: old]
+
+.SH SPELLING
+.IP "--spelling-dict=<dict name>"
+Spelling dictionary name. Available dictionaries: none. To make it work, install the python-enchant package. [default: none]
+.IP "--spelling-ignore-words=<comma separated words>"
+List of comma separated words that should not be checked. [default: none]
+.IP "--spelling-private-dict-file=<path to file>"
+A path to a file that contains the private dictionary; one word per line. [default: none]
+.IP "--spelling-store-unknown-words=<y_or_n>"
+Tells whether to store unknown words to the private dictionary (see the --spelling-private-dict-file option) instead of raising a message. [default: no]
+.IP "--max-spelling-suggestions=N"
+Limits count of emitted suggestions for spelling mistakes. [default: 4]
+
+.SH MISCELLANEOUS
+.IP "--notes=<comma separated values>"
+List of note tags to take in consideration, separated by a comma. [default: FIXME,XXX,TODO]
+.IP "--notes-rgx=<regexp>"
+Regular expression of note tags to take in consideration.
+
 .SH TYPECHECK
 .IP "--ignore-on-opaque-inference=<y_or_n>"
 This flag controls whether pylint should warn about no-member and similar checks whenever an opaque object is returned when inferring. The inference can return multiple potential results while evaluating a Python object, but some branches might not be evaluated, which results in partial inference. In that case, it might be useful to still emit no-member and other checks for the rest of the inferred objects. [default: yes]
@@ -127,46 +155,6 @@ Show a hint with possible names when a member name was not found. The aspect of
 .IP "--signature-mutators=<decorator names>"
 List of decorators that change the signature of a decorated function. [default: none]
 
-.SH LOGGING
-.IP "--logging-modules=<comma separated list>"
-Logging modules to check that the string format arguments are in logging function parameter format. [default: logging]
-.IP "--logging-format-style=<old (%) or new ({)>"
-Format style used to check logging format string. `old` means using % formatting, while `new` is for `{}` formatting. [default: old]
-
-.SH EXCEPTIONS
-.IP "--overgeneral-exceptions=<comma-separated class names>"
-Exceptions that will emit a warning when being caught. Defaults to "BaseException, Exception". [default: BaseException,Exception]
-
-.SH SIMILARITIES
-.IP "--min-similarity-lines=<int>"
-Minimum lines number of a similarity. [default: 4]
-.IP "--ignore-comments=<y or n>"
-Ignore comments when computing similarities. [default: yes]
-.IP "--ignore-docstrings=<y or n>"
-Ignore docstrings when computing similarities. [default: yes]
-.IP "--ignore-imports=<y or n>"
-Ignore imports when computing similarities. [default: no]
-
-.SH IMPORTS
-.IP "--deprecated-modules=<modules>"
-Deprecated modules which should not be used, separated by a comma. [default: optparse,tkinter.tix]
-.IP "--preferred-modules=<module:preferred-module>"
-Couples of modules and preferred modules, separated by a comma. [default: none]
-.IP "--import-graph=<file.dot>"
-Create a graph of every (i.e. internal and external) dependencies in the given file (report RP0402 must not be disabled). [default: none]
-.IP "--ext-import-graph=<file.dot>"
-Create a graph of external dependencies in the given file (report RP0402 must not be disabled). [default: none]
-.IP "--int-import-graph=<file.dot>"
-Create a graph of internal dependencies in the given file (report RP0402 must not be disabled). [default: none]
-.IP "--known-standard-library=<modules>"
-Force import order to recognize a module as part of the standard compatibility libraries. [default: none]
-.IP "--known-third-party=<modules>"
-Force import order to recognize a module as part of a third party library. [default: enchant]
-.IP "--analyse-fallback-blocks=<y_or_n>"
-Analyse import fallback blocks. This can be used to support both Python 2 and 3 compatible code, which means that the block might have code that exists only in one or another interpreter, leading to false positives when analysed. [default: no]
-.IP "--allow-wildcard-with-all=<y_or_n>"
-Allow wildcard imports from modules that define __all__. [default: no]
-
 .SH VARIABLES
 .IP "--init-import=<y_or_n>"
 Tells whether we should check for unused import in __init__ files. [default: no]
@@ -183,27 +171,11 @@ Argument names that match this expression will be ignored. Default to name with
 .IP "--allow-global-unused-variables=<y_or_n>"
 Tells whether unused global variables should be treated as a violation. [default: yes]
 
-.SH CLASSES
-.IP "--defining-attr-methods=<method names>"
-List of method names used to declare (i.e. assign) instance attributes. [default: __init__,__new__,setUp]
-.IP "--valid-classmethod-first-arg=<argument names>"
-List of valid names for the first argument in a class method. [default: cls]
-.IP "--valid-metaclass-classmethod-first-arg=<argument names>"
-List of valid names for the first argument in a metaclass class method. [default: cls]
-.IP "--exclude-protected=<protected access exclusions>"
-List of member names, which should be excluded from the protected access warning. [default: _asdict,_fields,_replace,_source,_make]
-
-.SH SPELLING
-.IP "--spelling-dict=<dict name>"
-Spelling dictionary name. Available dictionaries: none. To make it work, install the python-enchant package. [default: none]
-.IP "--spelling-ignore-words=<comma separated words>"
-List of comma separated words that should not be checked. [default: none]
-.IP "--spelling-private-dict-file=<path to file>"
-A path to a file that contains the private dictionary; one word per line. [default: none]
-.IP "--spelling-store-unknown-words=<y_or_n>"
-Tells whether to store unknown words to the private dictionary (see the --spelling-private-dict-file option) instead of raising a message. [default: no]
-.IP "--max-spelling-suggestions=N"
-Limits count of emitted suggestions for spelling mistakes. [default: 4]
+.SH REFACTORING
+.IP "--max-nested-blocks=<int>"
+Maximum number of nested blocks for function / method body [default: 5]
+.IP "--never-returning-functions=NEVER_RETURNING_FUNCTIONS"
+Complete name of functions that never returns. When checking for inconsistent-return-statements if a never returning function is called then it will be considered as an explicit return statement and no message will be printed. [default: sys.exit]
 
 .SH FORMAT
 .IP "--max-line-length=<int>"
@@ -225,11 +197,83 @@ Number of spaces of indent required inside a hanging or continued line. [default
 .IP "--expected-line-ending-format=<empty or LF or CRLF>"
 Expected format of line ending, e.g. empty (any line ending), LF or CRLF. [default: none]
 
+.SH IMPORTS
+.IP "--deprecated-modules=<modules>"
+Deprecated modules which should not be used, separated by a comma. [default: optparse,tkinter.tix]
+.IP "--preferred-modules=<module:preferred-module>"
+Couples of modules and preferred modules, separated by a comma. [default: none]
+.IP "--import-graph=<file.dot>"
+Create a graph of every (i.e. internal and external) dependencies in the given file (report RP0402 must not be disabled). [default: none]
+.IP "--ext-import-graph=<file.dot>"
+Create a graph of external dependencies in the given file (report RP0402 must not be disabled). [default: none]
+.IP "--int-import-graph=<file.dot>"
+Create a graph of internal dependencies in the given file (report RP0402 must not be disabled). [default: none]
+.IP "--known-standard-library=<modules>"
+Force import order to recognize a module as part of the standard compatibility libraries. [default: none]
+.IP "--known-third-party=<modules>"
+Force import order to recognize a module as part of a third party library. [default: enchant]
+.IP "--allow-any-import-level=<modules>"
+List of modules that can be imported at any level, not just the top level one. [default: none]
+.IP "--analyse-fallback-blocks=<y_or_n>"
+Analyse import fallback blocks. This can be used to support both Python 2 and 3 compatible code, which means that the block might have code that exists only in one or another interpreter, leading to false positives when analysed. [default: no]
+.IP "--allow-wildcard-with-all=<y_or_n>"
+Allow wildcard imports from modules that define __all__. [default: no]
+
+.SH EXCEPTIONS
+.IP "--overgeneral-exceptions=<comma-separated class names>"
+Exceptions that will emit a warning when being caught. Defaults to "BaseException, Exception". [default: BaseException,Exception]
+
+.SH CLASSES
+.IP "--defining-attr-methods=<method names>"
+List of method names used to declare (i.e. assign) instance attributes. [default: __init__,__new__,setUp,__post_init__]
+.IP "--valid-classmethod-first-arg=<argument names>"
+List of valid names for the first argument in a class method. [default: cls]
+.IP "--valid-metaclass-classmethod-first-arg=<argument names>"
+List of valid names for the first argument in a metaclass class method. [default: cls]
+.IP "--exclude-protected=<protected access exclusions>"
+List of member names, which should be excluded from the protected access warning. [default: _asdict,_fields,_replace,_source,_make]
+
+.SH SIMILARITIES
+.IP "--min-similarity-lines=<int>"
+Minimum lines number of a similarity. [default: 4]
+.IP "--ignore-comments=<y or n>"
+Ignore comments when computing similarities. [default: yes]
+.IP "--ignore-docstrings=<y or n>"
+Ignore docstrings when computing similarities. [default: yes]
+.IP "--ignore-imports=<y or n>"
+Ignore imports when computing similarities. [default: no]
+
+.SH DESIGN
+.IP "--max-args=<int>"
+Maximum number of arguments for function / method. [default: 5]
+.IP "--max-locals=<int>"
+Maximum number of locals for function / method body. [default: 15]
+.IP "--max-returns=<int>"
+Maximum number of return / yield for function / method body. [default: 6]
+.IP "--max-branches=<int>"
+Maximum number of branch for function / method body. [default: 12]
+.IP "--max-statements=<int>"
+Maximum number of statements in function / method body. [default: 50]
+.IP "--max-parents=<num>"
+Maximum number of parents for a class (see R0901). [default: 7]
+.IP "--max-attributes=<num>"
+Maximum number of attributes for a class (see R0902). [default: 7]
+.IP "--min-public-methods=<num>"
+Minimum number of public methods for a class (see R0903). [default: 2]
+.IP "--max-public-methods=<num>"
+Maximum number of public methods for a class (see R0904). [default: 20]
+.IP "--max-bool-expr=<num>"
+Maximum number of boolean expressions in an if statement (see R0916). [default: 5]
+
 .SH BASIC
 .IP "--good-names=<names>"
 Good variable names which should always be accepted, separated by a comma. [default: i,j,k,ex,Run,_]
+.IP "--good-names-rgxs=<names>"
+Good variable names regexes, separated by a comma. If names match any regex, they will always be accepted [default: none]
 .IP "--bad-names=<names>"
 Bad variable names which should always be refused, separated by a comma. [default: foo,bar,baz,toto,tutu,tata]
+.IP "--bad-names-rgxs=<names>"
+Bad variable names regexes, separated by a comma. If names match any regex, they will always be refused [default: none]
 .IP "--name-group=<name1:name2>"
 Colon-delimited sets of names that determine each other's naming style when the name regexes allow several styles. [default: none]
 .IP "--include-naming-hint=<y_or_n>"
@@ -281,43 +325,11 @@ Regular expression which should only match function or class names that do not r
 .IP "--docstring-min-length=<int>"
 Minimum line length for functions/classes that require docstrings, shorter ones are exempt. [default: -1]
 
-.SH MISCELLANEOUS
-.IP "--notes=<comma separated values>"
-List of note tags to take in consideration, separated by a comma. [default: FIXME,XXX,TODO]
-.IP "--notes-rgx=<regexp>"
-Regular expression of note tags to take in consideration.
-
-.SH DESIGN
-.IP "--max-args=<int>"
-Maximum number of arguments for function / method. [default: 5]
-.IP "--max-locals=<int>"
-Maximum number of locals for function / method body. [default: 15]
-.IP "--max-returns=<int>"
-Maximum number of return / yield for function / method body. [default: 6]
-.IP "--max-branches=<int>"
-Maximum number of branch for function / method body. [default: 12]
-.IP "--max-statements=<int>"
-Maximum number of statements in function / method body. [default: 50]
-.IP "--max-parents=<num>"
-Maximum number of parents for a class (see R0901). [default: 7]
-.IP "--max-attributes=<num>"
-Maximum number of attributes for a class (see R0902). [default: 7]
-.IP "--min-public-methods=<num>"
-Minimum number of public methods for a class (see R0903). [default: 2]
-.IP "--max-public-methods=<num>"
-Maximum number of public methods for a class (see R0904). [default: 20]
-.IP "--max-bool-expr=<num>"
-Maximum number of boolean expressions in an if statement (see R0916). [default: 5]
-
-.SH REFACTORING
-.IP "--max-nested-blocks=<int>"
-Maximum number of nested blocks for function / method body [default: 5]
-.IP "--never-returning-functions=NEVER_RETURNING_FUNCTIONS"
-Complete name of functions that never returns. When checking for inconsistent-return-statements if a never returning function is called then it will be considered as an explicit return statement and no message will be printed. [default: sys.exit]
-
 .SH STRING
 .IP "--check-str-concat-over-line-jumps=<y_or_n>"
-This flag controls whether the implicit-str-concat-in-sequence should generate a warning on implicit string concatenation in sequences defined over several lines. [default: no]
+This flag controls whether the implicit-str-concat should generate a warning on implicit string concatenation in sequences defined over several lines. [default: no]
+.IP "--check-quote-consistency=<y_or_n>"
+This flag controls whether inconsistent-quotes generates a warning when the character used as a quote delimiter is used inconsistently within a module. [default: no]
 
 .SH ENVIRONMENT VARIABLES
 
@@ -331,28 +343,28 @@ directory).
 to search for configuration file.
 
 .SH OUTPUT
-Using the default text output, the message format is :                          
-                                                                                
-        MESSAGE_TYPE: LINE_NUM:[OBJECT:] MESSAGE                                
-                                                                                
-There are 5 kind of message types :                                             
-    * (C) convention, for programming standard violation                        
-    * (R) refactor, for bad code smell                                          
-    * (W) warning, for python specific problems                                 
-    * (E) error, for probable bugs in the code                                  
+Using the default text output, the message format is :
+
+        MESSAGE_TYPE: LINE_NUM:[OBJECT:] MESSAGE
+
+There are 5 kind of message types :
+    * (C) convention, for programming standard violation
+    * (R) refactor, for bad code smell
+    * (W) warning, for python specific problems
+    * (E) error, for probable bugs in the code
     * (F) fatal, if an error occurred which prevented pylint from doing further
 processing.
 
 .SH OUTPUT STATUS CODE
-Pylint should leave with following status code:                                 
-    * 0 if everything went fine                                                 
-    * 1 if a fatal message was issued                                           
-    * 2 if an error message was issued                                          
-    * 4 if a warning message was issued                                         
-    * 8 if a refactor message was issued                                        
-    * 16 if a convention message was issued                                     
-    * 32 on usage error                                                         
-                                                                                
+Pylint should leave with following status code:
+    * 0 if everything went fine
+    * 1 if a fatal message was issued
+    * 2 if an error message was issued
+    * 4 if a warning message was issued
+    * 8 if a refactor message was issued
+    * 16 if a convention message was issued
+    * 32 on usage error
+
 status 1 to 16 will be bit-ORed so you can know which different categories has
 been issued by analysing pylint output status code
 
@@ -365,4 +377,3 @@ mailto:code-quality@python.org
 
 .SH AUTHOR
 Python Code Quality Authority <code-quality@python.org>
-