Add raw command to docs

docs/commandline.rst

@@ -12,12 +12,13 @@ The :command:`cc` command
 
 .. program:: cc
 
-Analyze Python source files and compute Cyclomatic Complexity. The output can
-be filtered by specifying the :option:`-n` and :option:`-x` flags. By
-default, the complexity score is not displayed, the option :option:`-s` (show
-complexity) toggles this behaviour. File or directories exclusion is supported
-through glob patterns. Every positional argument is interpreted as a path. The
-program then walks through its children and analyzes Python files.
+This command analyzes Python source files and compute Cyclomatic Complexity.
+The output can be filtered by specifying the :option:`-n` and :option:`-x`
+flags. By default, the complexity score is not displayed, the option
+:option:`-s` (show complexity) toggles this behaviour. File or directories
+exclusion is supported through glob patterns. Every positional argument is
+interpreted as a path. The program then walks through its children and analyzes
+Python files.
 Every block will be ranked from A (best complexity score) to F (worst one).
 Ranks corresponds to complexity scores as follows:
 
@@ -62,7 +63,7 @@ Examples
     $ radon cc path
 
 Radon will walk through the subdirectories of path and will analyze all
-children nodes (every Python file it encounters).
+child nodes (every Python file it encounters).
 
 ::
 
@@ -88,7 +89,8 @@ The :command:`mi` command
 
 .. program:: mi
 
-Analyzes Python source code files and compute the Maintainability Index score.
+The command analyzes Python source code files and compute the Maintainability
+Index score.
 Every positional argument is treated as a starting point from which to walk
 looking for Python files (as in the :command:`cc` command). Paths can be
 excluded with the :option:`-e` option.
@@ -132,7 +134,7 @@ every subdirectory.
 
     $ radon mi path1 -e "path1/tests/*"
 
-Like the previous example, but it exclude from the analysis every path that
+Like the previous example, but excluding from the analysis every path that
 matches `path1/tests/*`.
 
 ::
@@ -145,5 +147,40 @@ Like the previous examples, but does not count multiline strings as comments.
 The :command:`raw` command
 --------------------------
 
+This command analyzes the given Python modules in order to compute raw metrics.
+These include:
+
+    * **LOC**: the total number of lines of code
+    * **LLOC**: the number of logical lines of code
+    * **SLOC**: the number of source lines of code - not necessarily
+      corresponding to the **LLOC** [WikiRef]_
+    * **comments**: the number of Python comment lines (i.e. only single-line
+      comments ``#``)
+    * **multi**: the number of lines representing multi-line strings
+    * **blank**: the number of blank lines (or whitespace-only ones)
+
+The equation :math:`sloc + blank = loc` should always hold.
+
+.. [WikiRef] More information here: http://en.wikipedia.org/wiki/Source_lines_of_code
+
+.. option:: -e, --exclude
+
+    A comma-separated list of patterns which indicate which paths to exclude
+    from the analysis.
+
 Examples
 ++++++++
+
+::
+
+    $ radon raw path1 path2
+
+Analyze every Python file under *path1* or *path2*. It checks recursively in
+every subdirectory.
+
+::
+
+    $ radon raw path1 -e "path1/tests/*"
+
+Like the previous example, but excluding from the analysis every path that
+matches ``path1/tests/*``.

docs/intro.rst

@@ -54,13 +54,13 @@ Common formulas are:
 * the derivative used by SEI:
 
   .. math::
-  
+
     MI = 171 - 5.2\log_2 V - 0.23 G - 16.2 \log_2 L + 50 \sin(\sqrt{2.4 C})
 
 * the derivative used by Visual Studio:
-  
+
   .. math::
-  
+
     MI = max \left [ 0, 100\dfrac{171 - 5.2\ln V - 0.23 G - 16.2 \ln L}{171} \right ].
 
 Radon uses another derivative, computed from both SEI derivative and Visual
@@ -71,7 +71,7 @@ Studio one:
     MI = max \left [ 0, 100\dfrac{171 - 5.2\ln V - 0.23 G - 16.2 \ln L + 50 \sin(\sqrt{2.4 C}))}{171} \right ]
 
 Where:
-    * ``V`` is the Halstead Volume;
+    * ``V`` is the Halstead Volume (see below);
     * ``G`` is the total Cyclomatic Complexity;
     * ``L`` is the number of Source Lines of Code (SLOC);
     * ``C`` is the percent of comment lines (important: converted to radians).