Refresh the docs a bit in preparation for the release

1 files changed, 129 insertions, 118 deletions

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>
-