Improve tests and docs

lib/credo/check.ex

@@ -1,9 +1,15 @@
 defmodule Credo.Check do
-  @doc """
+  @moduledoc """
   `Check` modules represent the checks which are run during the code analysis.
+
+  Example:
+
+      defmodule MyCheck do
+        use Credo.Check, category: :warning, base_priority: :high, elixir_version: ">= 1.3"
+      end
   """
 
-  alias Credo.Priority
+  @type t :: module
 
   @base_category_exit_status_map %{
     consistency: 1,
@@ -13,8 +19,9 @@ defmodule Credo.Check do
     warning: 16
   }
 
-  @type t :: module
+  alias Credo.Priority
 
+  @doc false
   defmacro __using__(opts) do
     quote do
       @behaviour Credo.Check

lib/credo/check/code_helper.ex

@@ -50,6 +50,8 @@ defmodule Credo.Check.CodeHelper do
       true
 
   """
+  def matches?(name, value)
+
   def matches?(name, list) when is_list(list) do
     Enum.any?(list, &matches?(name, &1))
   end
@@ -69,8 +71,8 @@ defmodule Credo.Check.CodeHelper do
 
   Examples:
 
-    {:defmodule, "Foo.Bar"}
-    {:def, "Foo.Bar.baz"}
+      {:defmodule, "Foo.Bar"}
+      {:def, "Foo.Bar.baz"}
   """
   def scope_for(source_file, line: line_no) do
     source_file

lib/credo/check/config_comment.ex

@@ -1,16 +1,31 @@
 defmodule Credo.Check.ConfigComment do
-  defstruct line_no: nil,
-            line_no_end: nil,
-            instruction: nil,
-            params: nil
+  @moduledoc """
+  `ConfigComment` structs represent comments which follow control Credo's behaviour.
 
-  alias Credo.Issue
+  The following comments are supported:
+
+      # credo:disable-for-this-file
+      # credo:disable-for-next-line
+      # credo:disable-for-previous-line
+      # credo:disable-for-lines:<number>
+
+  """
 
   @instruction_disable_file "disable-for-this-file"
   @instruction_disable_next_line "disable-for-next-line"
   @instruction_disable_previous_line "disable-for-previous-line"
   @instruction_disable_lines "disable-for-lines"
 
+  alias Credo.Issue
+
+  defstruct line_no: nil,
+            line_no_end: nil,
+            instruction: nil,
+            params: nil
+
+  @doc "Returns a `ConfigComment` struct based on the given parameters."
+  def new(instruction, param_string, line_no)
+
   def new("#{@instruction_disable_lines}:" <> line_count, param_string, line_no) do
     line_count = String.to_integer(line_count)
 
@@ -44,6 +59,9 @@ defmodule Credo.Check.ConfigComment do
     }
   end
 
+  @doc "Returns `true` if the given `issue` should be ignored based on the given `config_comment`"
+  def ignores_issue?(config_comment, issue)
+
   def ignores_issue?(
         %__MODULE__{instruction: @instruction_disable_file, params: params},
         %Issue{} = issue
@@ -92,6 +110,8 @@ defmodule Credo.Check.ConfigComment do
     false
   end
 
+  #
+
   defp params_ignore_issue?([], _issue) do
     true
   end

lib/credo/check/config_comment_finder.ex

@@ -1,6 +1,11 @@
 defmodule Credo.Check.ConfigCommentFinder do
   @moduledoc """
+  This check is used internally by Credo.
+
+  It traverses the given codebase to find `Credo.Check.ConfigComment`
+  compatible comments, which control Credo's behaviour.
   """
+
   @explanation nil
   @config_comment_format ~r/#\s*credo\:([\w-\:]+)\s*(.*)/im
 

lib/credo/check/params.ex

@@ -1,5 +1,19 @@
 defmodule Credo.Check.Params do
-  @doc "Returns the given `field`'s params value."
+  @moduledoc """
+  This module provides functions for handling parameters ("params") given to
+  checks through `.credo.exs` (i.e. the `Credo.ConfigFile`).
+  """
+
+  @doc """
+  Returns the given `field`'s `params` value.
+
+  Example:
+
+      iex> Credo.Check.Params.get([], :foo, [foo: "bar"])
+      "bar"
+      iex> Credo.Check.Params.get([foo: "baz"], :foo, [foo: "bar"])
+      "baz"
+  """
   def get(params, field, default_params \\ []) when is_list(params) do
     case params[field] do
       nil ->

lib/credo/check/readability/semicolons.ex

@@ -3,6 +3,15 @@ defmodule Credo.Check.Readability.Semicolons do
   Don't use ; to separate statements and expressions.
   Statements and expressions should be separated by lines.
 
+      # preferred
+
+      a = 1
+      b = 2
+
+      # NOT preferred
+
+      a = 1; b = 2
+
   Like all `Readability` issues, this one is not a technical concern.
   But you can improve the odds of others reading and liking your code by making
   it easier to follow.

lib/credo/check/readability/trailing_blank_line.ex

@@ -3,7 +3,7 @@ defmodule Credo.Check.Readability.TrailingBlankLine do
   Files should end in a trailing blank line.
 
   This is mostly for historical reasons: every text file should end with a \\n,
-  or newline since this acts as `eol´ or the end of the line character.
+  or newline since this acts as `eol` or the end of the line character.
 
   See also: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_206
 

lib/credo/check/refactor/abc_size.ex

@@ -23,11 +23,11 @@ defmodule Credo.Check.Refactor.ABCSize do
   @branch_ops [:.]
   @condition_ops [:if, :unless, :for, :try, :case, :cond, :and, :or, :&&, :||]
 
+  use Credo.Check
+
   alias Credo.Check.CodeHelper
   alias Credo.SourceFile
 
-  use Credo.Check
-
   @doc false
   def run(source_file, params \\ []) do
     issue_meta = IssueMeta.for(source_file, params)

lib/credo/check/refactor/cyclomatic_complexity.ex

@@ -38,11 +38,11 @@ defmodule Credo.Check.Refactor.CyclomaticComplexity do
     cond: 1
   ]
 
+  use Credo.Check
+
   alias Credo.Check.CodeHelper
   alias Credo.SourceFile
 
-  use Credo.Check
-
   @doc false
   def run(source_file, params \\ []) do
     issue_meta = IssueMeta.for(source_file, params)

lib/credo/check/refactor/function_arity.ex

@@ -16,10 +16,10 @@ defmodule Credo.Check.Refactor.FunctionArity do
   @default_params [max_arity: 8, ignore_defp: false]
   @def_ops [:def, :defp, :defmacro]
 
-  alias Credo.Code.Parameters
-
   use Credo.Check
 
+  alias Credo.Code.Parameters
+
   @doc false
   def run(source_file, params \\ []) do
     issue_meta = IssueMeta.for(source_file, params)

lib/credo/check/refactor/nesting.ex

@@ -32,10 +32,10 @@ defmodule Credo.Check.Refactor.Nesting do
   @def_ops [:def, :defp, :defmacro]
   @nest_ops [:if, :unless, :case, :cond, :fn]
 
-  alias Credo.Check.CodeHelper
-
   use Credo.Check
 
+  alias Credo.Check.CodeHelper
+
   @doc false
   def run(source_file, params \\ []) do
     issue_meta = IssueMeta.for(source_file, params)

lib/credo/check/refactor/perceived_complexity.ex

@@ -38,11 +38,11 @@ defmodule Credo.Check.Refactor.PerceivedComplexity do
     cond: 1
   ]
 
+  use Credo.Check
+
   alias Credo.Check.CodeHelper
   alias Credo.SourceFile
 
-  use Credo.Check
-
   @doc false
   def run(source_file, params \\ []) do
     issue_meta = IssueMeta.for(source_file, params)

lib/credo/check/refactor/variable_rebinding.ex

@@ -32,10 +32,10 @@ defmodule Credo.Check.Refactor.VariableRebinding do
     check: @moduledoc
   ]
 
-  alias Credo.Check.CodeHelper
-
   use Credo.Check
 
+  alias Credo.Check.CodeHelper
+
   @doc false
   def run(source_file, params \\ []) do
     issue_meta = IssueMeta.for(source_file, params)

lib/credo/check/runner.ex

@@ -1,4 +1,9 @@
 defmodule Credo.Check.Runner do
+  @moduledoc """
+  This module is responsible for running checks based on the context represented
+  by the current `Credo.Execution`.
+  """
+
   alias Credo.CLI.Output.UI
   alias Credo.Execution
   alias Credo.Execution.Issues
@@ -38,7 +43,7 @@ defmodule Credo.Check.Runner do
     :ok
   end
 
-  @doc "Runs the ConfigCommentFinder"
+  @doc "Runs the ConfigCommentFinder."
   def run_config_comment_finder(source_files, exec) do
     {Credo.Check.ConfigCommentFinder}
     |> run_check(source_files, exec)

lib/credo/cli.ex

@@ -1,6 +1,6 @@
 defmodule Credo.CLI do
   @moduledoc """
-  Credo.CLI is the entrypoint for both the Mix task and the escript.
+  `Credo.CLI` is the entrypoint for both the Mix task and the escript.
 
   It takes the parameters passed from the command line and translates them into
   a Command module (see the `Credo.CLI.Command` namespace), the work directory

lib/credo/cli/filename.ex

@@ -1,5 +1,7 @@
 defmodule Credo.CLI.Filename do
-  @moduledoc false
+  @moduledoc """
+  This module can be used to handle filenames given at the command line.
+  """
 
   @doc """
   Returns `true` if a given `filename` contains a pos_suffix.

lib/credo/cli/options.ex

@@ -1,10 +1,7 @@
 defmodule Credo.CLI.Options do
-  defstruct command: nil,
-            path: nil,
-            args: [],
-            switches: nil,
-            unknown_switches: [],
-            unknown_args: []
+  @moduledoc """
+  The `Options` struct represents the options given on the command line.
+  """
 
   @switches [
     all_priorities: :boolean,
@@ -39,6 +36,20 @@ defmodule Credo.CLI.Options do
 
   alias Credo.Priority
 
+  defstruct command: nil,
+            path: nil,
+            args: [],
+            switches: nil,
+            unknown_switches: [],
+            unknown_args: []
+
+  @doc """
+  Returns a `Options` struct for the given parameters.
+
+      iex> Credo.CLI.Options.parse(["alice", "--debug"], ".", ["alice", "bob", "eve"], [])
+      %Credo.CLI.Options{args: [], command: "alice", path: ".", switches: %{debug: true}, unknown_args: [], unknown_switches: []}
+
+  """
   def parse(argv, current_dir, command_names, ignored_args) do
     argv
     |> OptionParser.parse(strict: @switches, aliases: @aliases)

lib/credo/cli/output.ex

@@ -1,9 +1,13 @@
 defmodule Credo.CLI.Output do
-  alias Credo.CLI.Output.UI
-  alias Credo.Execution
+  @moduledoc """
+  This module provides helper functions regarding command line output.
+  """
 
   @category_tag_map %{"refactor" => "F"}
 
+  alias Credo.CLI.Output.UI
+  alias Credo.Execution
+
   def check_tag(category, in_parens \\ true)
 
   def check_tag(category, in_parens) when is_binary(category) do

lib/credo/cli/output/format_delegator.ex

@@ -1,9 +1,19 @@
 defmodule Credo.CLI.Output.FormatDelegator do
   @moduledoc """
-  The FormatDelegator module can be used to easily delegate print-statements
-  for different formats to different modules.
+  This module can be used to easily delegate print-statements for different
+  formats to different modules.
+
+  Example:
+
+      use Credo.CLI.Output.FormatDelegator,
+        default: Credo.CLI.Command.Suggest.Output.Default,
+        flycheck: Credo.CLI.Command.Suggest.Output.FlyCheck,
+        oneline: Credo.CLI.Command.Suggest.Output.Oneline,
+        json: Credo.CLI.Command.Suggest.Output.Json
+
   """
 
+  @doc false
   defmacro __using__(format_list) do
     format_mods =
       Enum.map(format_list, fn {format, output_mod} ->

lib/credo/cli/output/shell.ex

@@ -1,7 +1,8 @@
 defmodule Credo.CLI.Output.Shell do
   @moduledoc """
-  GenServer used by Credo.CLI.Output.UI to write to the shell.
+  This module is used by `Credo.CLI.Output.UI` to write to the shell.
   """
+
   use GenServer
 
   def start_link(opts \\ []) do

lib/credo/cli/output/summary.ex

@@ -1,8 +1,7 @@
 defmodule Credo.CLI.Output.Summary do
-  alias Credo.CLI.Output
-  alias Credo.CLI.Output.UI
-  alias Credo.Execution
-  alias Credo.SourceFile
+  @moduledoc """
+  This module is responsible for printing the summary at the end of the analysis.
+  """
 
   @category_wording [
     {:consistency, "consistency issue", "consistency issues"},
@@ -13,6 +12,11 @@ defmodule Credo.CLI.Output.Summary do
   ]
   @cry_for_help "Please report incorrect results: https://github.com/rrrene/credo/issues"
 
+  alias Credo.CLI.Output
+  alias Credo.CLI.Output.UI
+  alias Credo.Execution
+  alias Credo.SourceFile
+
   def print(
         _source_files,
         %Execution{format: "flycheck"},

lib/credo/cli/output/ui.ex

@@ -1,4 +1,8 @@
 defmodule Credo.CLI.Output.UI do
+  @moduledoc """
+  This module provides functions used to create the UI.
+  """
+
   @edge "┃"
   @ellipsis "…"
   @shell_service Credo.CLI.Output.Shell