docs(improve moduledocs): improve moduledocs

README.md

@@ -27,6 +27,7 @@ Use at your peril, _for now._
 ## Roadmap TODO
 
   - [] Add and configure CHANGELOG tracking.
+  - [] Add test for one file containing more than one `defmodule`
   - [] How does this work with macro code? Does that even make sense as a case to handle?
   - [] Update .exs files too?
   - [] update test file refs by CLI option

lib/ex_factor/changer.ex

@@ -1,6 +1,7 @@
 defmodule ExFactor.Changer do
   @moduledoc """
-  Documentation for `ExFactor.Changer`.
+  `ExFactor.Changer` find all references to the old (source) Mod.function/arity and update
+  the calls to use the new (target) Mod.function/arity.
   """
 
   alias ExFactor.Callers

lib/ex_factor/extractor.ex

@@ -1,6 +1,8 @@
 defmodule ExFactor.Extractor do
   @moduledoc """
-  Documentation for `ExFactor.Extractor`.
+  `ExFactor.Extractor` finds the targetd function and places it in a different module.
+
+  Create the new (target) module path  and file if necessary.
   """
   alias ExFactor.Neighbors
   alias ExFactor.Parser

lib/ex_factor/formatter.ex

@@ -1,7 +1,6 @@
 defmodule ExFactor.Formatter do
   @moduledoc """
-  Documentation for `ExFactor.Formatter`.
-  Format a list of files
+  `ExFactor.Formatter` Format a list of files
   """
 
   def format([nil]), do: nil

lib/ex_factor/parser.ex

@@ -1,11 +1,13 @@
 defmodule ExFactor.Parser do
   @moduledoc """
-  Documentation for `ExFactor.Parser`.
+  `ExFactor.Parser` we're making some assumptions that you're using this library within the
+  context of a Mix app and that every file contains one or more `defmodule` blocks.
   """
 
-  # @doc """
-  # Identify public and private functions from a module AST.
-  # """
+  @doc """
+  Parse the contents of a filepath in an Abstract Syntaxt Tree (AST) and
+  extraxct the block contents of the module at the filepath.
+  """
   def read_file(filepath) when is_binary(filepath) do
     contents = File.read!(filepath)
     list = String.split(contents, "\n")

lib/ex_factor/remover.ex

@@ -1,6 +1,8 @@
 defmodule ExFactor.Remover do
   @moduledoc """
-  Documentation for `ExFactor.Remover`.
+  `ExFactor.Remover` Remove the indicated function and its spec from it's original file.
+
+  It's safer to add rather than remove multiple attributes.
   """
   alias ExFactor.Parser