Cleanup through documentation.

5 files changed, 28 insertions, 23 deletions

diff --git a/doc/contribute.rst b/doc/contribute.rst
index 6a45dea..43e5dfb 100644
--- a/doc/contribute.rst
+++ b/doc/contribute.rst
@@ -47,7 +47,7 @@ http://lists.logilab.org/pipermail/python-projects/
 Forge
 -----
 
-Pylint is developped using the mercurial_ distributed version control system.
+Pylint is developed using the mercurial_ distributed version control system.
 
 You can clone Pylint and its dependencies from ::
 
@@ -64,7 +64,7 @@ your patch gets accepted.
 
     - Pylint keeps a set of unit tests in the /test directory. The
       `test_func.py` module uses external files to have some kind of easy
-      functionnal testing. To get your patch accepted you must write (or change)
+      functional testing. To get your patch accepted you must write (or change)
       a test input file in the `test/input` directory and message file in the
       `test/messages` directory. Then run `python test_func.py` to ensure that
       your test is green.
@@ -117,7 +117,7 @@ without installing them.  You can run all the unit tests like so::
 The -S flag keeps distutils from interfering with sys.path.  YMMV.
 
 
-Adding new functionnal tests
+Adding new functional tests
 ----------------------------
 
 Pylint comes with an easy way to write functional tests for new checks:
diff --git a/doc/extend.rst b/doc/extend.rst
index 476c994..b767852 100644
--- a/doc/extend.rst
+++ b/doc/extend.rst
@@ -8,7 +8,8 @@ You can find some simple examples in the examples
 directory of the distribution (custom.py and custom_raw.py). I'll try to
 quickly explain the essentials here.
 
-First, there are two kinds of checkers :
+First, there are two kinds of checkers:
+
 * raw checkers, which are analysing each module as a raw file stream
 * ast checkers, which are working on an ast representation of the module
 
@@ -25,8 +26,8 @@ Checkers are ordered by priority. For each module, Pylint's engine:
 
 1. give the module source file as a stream to raw checkers
 2. get an ast representation for the module
-3. make a depth first descent of the tree, calling visit_<> on each AST
-   checker when entering a node, and living_<> on the back traversal
+3. make a depth first descent of the tree, calling ``visit_<>`` on each AST
+   checker when entering a node, and ``leave_<>`` on the back traversal
 
 Notice that the source code is probably the best source of
 documentation, it should be clear and well documented. Don't hesitate to
diff --git a/doc/faq.rst b/doc/faq.rst
index 7e2f3cc..c81bbc3 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -1,5 +1,7 @@
 .. -*- coding: utf-8 -*-
 
+.. _faq:
+
 ==========================
 Frequently Asked Questions
 ==========================
@@ -169,7 +171,6 @@ No, starting from 0.25.3, you can use symbolic names for messages::
 
     # pylint: disable=fixme, line-too-long
 
-You can show these symbols in the output with the `-sy` option.
 
 4.5 I have a callback function where I have no control over received arguments. How do I avoid getting unused argument warnings?
 ----------------------------------------------------------------------------------------------------------------------------------
diff --git a/doc/output.rst b/doc/output.rst
index 3a87547..537bfcb 100644
--- a/doc/output.rst
+++ b/doc/output.rst
@@ -33,7 +33,7 @@ C
 category
     fullname of the message category
 
-For exemple the former (pre 1.0) default format can be obtained with::
+For example, the former (pre 1.0) default format can be obtained with::
 
   pylint --msg-template='{msg_id}:{line:3d},{column}: {obj}: {msg}'
 
diff --git a/doc/run.rst b/doc/run.rst
index 9b2b218..418e915 100644
--- a/doc/run.rst
+++ b/doc/run.rst
@@ -31,9 +31,9 @@ directory is automatically added on top of the python path ::
 will work if "directory" is a python package (i.e. has an __init__.py
 file) or if "directory" is in the python path.
 
-For more details on this see the Frequently Asked Questions.
+For more details on this see the :ref:`faq`.
 
-You can also start a thin gui around Pylint (require TkInter) by
+You can also start a thin gui around Pylint (require tkinter) by
 typing ::
 
   pylint-gui
@@ -43,7 +43,7 @@ or module to check, at Pylint messages will be displayed in the user
 interface.
 
 It is also possible to call Pylint from an other python program,
-thanks to ``py_run()`` function in ``lint`` module,
+thanks to ``py_run()`` function in ``epylint`` module,
 assuming Pylint options are stored in ``pylint_options`` string, as:
 
 .. sourcecode:: python
@@ -57,7 +57,7 @@ and get its standard output and error:
 .. sourcecode:: python
 
   from pylint import epylint as lint
-  (pylint_stdout, pylint_stderr) = lint.py_run('module_name.py', True)
+  (pylint_stdout, pylint_stderr) = lint.py_run('module_name.py', return_std=True)
 
 
 Command line options
@@ -134,20 +134,23 @@ Other useful global options include:
 Parallel execution
 ------------------
 
-It is possible to speed up the execution of Pylint. If the running computer has more CPUs than one
-then the files to be checked could be spread on all processors to Pylint sub-processes.
-This functionality is exposed via ``-j`` command line parameter. It takes a number of sub-processes
-that should be spawned. If provided number is 0 then the number of CPUs will be taken.
-Default number is 1.
+It is possible to speed up the execution of Pylint. If the running computer
+has more CPUs than one, then the files to be checked could be spread on all
+processors to Pylint sub-processes.
+This functionality is exposed via ``-j`` command line parameter.
+It takes a number of sub-processes that should be spawned.
+If the provided number is 0 then the number of CPUs will be used.
+The default number of workers is 1.
 
 Example::
 
   pylint -j 4 mymodule1.py mymodule2.py mymodule3.py mymodule4.py
 
-This will spawn 4 parallel Pylint sub-process. Each provided module will be checked in parallel.
-Discovered problems by checkers are not displayed immediatelly. They are shown just after completing
-checking a module.
+This will spawn 4 parallel Pylint sub-process, where each provided module will
+be checked in parallel. Discovered problems by checkers are not displayed
+immediately. They are shown just after completing checking a module.
 
-There are some limitations in running checks in parallel in current implementation.
-It is not possible to use custom plugins (i.e. ``--load-plugins`` option).
-It is also not possible to use initialization hook (i.e. ``--init-hook`` option).
+There are some limitations in running checks in parallel in current
+implementation. It is not possible to use custom plugins
+(i.e. ``--load-plugins`` option), nor it is not possible to use
+initialization hooks (i.e. ``--init-hook`` option).