Update docs

man/crystal.1

@@ -368,6 +368,10 @@ Show implementations for a given call. Use
 to specify the cursor position. The format for the cursor position is file:line:column.
 .It Cm types
 Show type of main variables of file.
+.It Cm unreachable
+Show methods that are never called. The output is a list of lines with columns
+separated by tab. The first column is the location of the def, the second column
+its reference name and the third column is the length in lines.
 .El
 .Pp
 .It

src/compiler/crystal/command.cr

@@ -44,7 +44,7 @@ class Crystal::Command
         format                   format project, directories and/or files
         hierarchy                show type hierarchy
         implementations          show implementations for given call in location
-        unreachable              show code that is never used
+        unreachable              show methods that is never called
         types                    show type of main variables
         --help, -h               show this help
     USAGE

src/compiler/crystal/tools/unreachable.cr

@@ -53,9 +53,12 @@ module Crystal
     end
   end
 
-  # Some defs (yielding, generic or virtual owner) are separate
-  # instantiations and thus cannot be identified by a unique object_id. Thus
-  # we're looking for location to identify the base def.
+  # This visitor walks the entire reachable code tree and collect locations
+  # of all defs that are a target of a call into `@used_def_locations`.
+  # The locations are filtered to only those that we're interested in per
+  # `@includes` and `@excludes`.
+  # Then it traverses all types and their defs and reports those that are not
+  # in `@used_def_locations` (and match the filter).
   class UnreachableVisitor < Visitor
     @used_def_locations = Set(Location).new
     @defs = [] of Def