Merge pull request #425 from kianmeng/misc-doc-changes

Misc doc changes

CHANGELOG.md

@@ -14,7 +14,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
  - Warning pretty printing and message fixes/improvements.
  - Prevent crash when short_format fails.
  - Ensure path to PLT target directory exists.
- - Bumpe required `erlex` for formatting fix.
+ - Bumped required `erlex` for formatting fix.
 
 ## [1.0.0-rc.7] - 2019-09-21
 

README.md

@@ -1,8 +1,13 @@
 # Dialyxir
 
-Mix tasks to simplify use of Dialyzer in Elixir projects.
-
 [![Build Status](https://travis-ci.org/jeremyjh/dialyxir.svg?branch=master)](https://travis-ci.org/jeremyjh/dialyxir)
+[![Module Version](https://img.shields.io/hexpm/v/dialyxir.svg)](https://hex.pm/packages/dialyxir)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/dialyxir/)
+[![Total Download](https://img.shields.io/hexpm/dt/dialyxir.svg)](https://hex.pm/packages/dialyxir)
+[![License](https://img.shields.io/hexpm/l/dialyxir.svg)](https://github.com/jeremyjh/dialyxir/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/jeremyjh/dialyxir.svg)](https://github.com/jeremyjh/dialyxir/commits/master)
+
+Mix tasks to simplify use of Dialyzer in Elixir projects.
 
 ## Changes in 1.0
 
@@ -53,10 +58,11 @@ mix dialyzer
   *  `--format dialyzer`   - format the warnings in the original Dialyzer format
   *  `--quiet`             - suppress all informational messages
 
-Warning flags passed to this task are passed on to `:dialyzer`.
+Warning flags passed to this task are passed on to `:dialyzer` - e.g.
 
-  e.g.
-    `mix dialyzer --unmatched_returns`
+```console
+mix dialyzer --unmatched_returns
+```
 
 There is information available about the warnings via the explain task - e.g.
 
@@ -69,6 +75,7 @@ If invoked without arguments, `mix dialyzer.explain` will list all the known war
 ## Continuous Integration
 
 To use Dialyzer in CI, you must be aware of several things:
+
 1) Building the PLT file may take a while if a project has many dependencies
 2) The PLT should be cached using the CI caching system
 3) The PLT will need to be rebuilt whenever adding a new Erlang or Elixir version to build matrix
@@ -121,17 +128,18 @@ Usage is straightforward but you should be aware of the available configuration
 ### PLT
 
 The Persistent Lookup Table (PLT) is basically a cached output of the analysis. This is important because you'd probably stab yourself in the eye with
-a fork if you had to wait for Dialyzer to analyze all the standard library and OTP modules you are using everytime you ran it.
+a fork if you had to wait for Dialyzer to analyze all the standard library and OTP modules you are using every time you ran it.
 Running the mix task `dialyzer` by default builds several PLT files:
-  * A core Erlang file in $MIX_HOME/dialyxir_erlang-[OTP Version].plt
-  * A core Elixir file in $MIX_HOME/dialyxir_erlang-[OTP Version]_elixir-[Elixir Version].plt
-  * A project environment specific file in _build/env/dialyze_erlang-[OTP Version]_elixir-[Elixir Version]_deps-dev.plt
+
+  * A core Erlang file in `$MIX_HOME/dialyxir_erlang-[OTP Version].plt`
+  * A core Elixir file in `$MIX_HOME/dialyxir_erlang-[OTP Version]_elixir-[Elixir Version].plt`
+  * A project environment specific file in `_build/env/dialyze_erlang-[OTP Version]_elixir-[Elixir Version]_deps-dev.plt`
 
 The core files are simply copied to your project folder when you run `dialyxir` for the first time with a given version of Erlang and Elixir. By default, all
-the modules in the project PLT are checked against your dependencies to be sure they are up to date. If you do not want to use MIX_HOME to store your core Erlang and Elixir files, you can provide a :plt_core_path key with a file path. You can specify a different directory for the project PLT file with the :plt_local_path keyword. You can specify a different filename for the project PLT file with the :plt_file keyword - this is deprecated because people were using it with the old `dialyxir` to have project-specific PLTs, which are now the default. To silence the deprecation warning, specify this value as `plt_file: {:no_warn, "/myproject/mypltfile"}`.
+the modules in the project PLT are checked against your dependencies to be sure they are up to date. If you do not want to use MIX_HOME to store your core Erlang and Elixir files, you can provide a `:plt_core_path` key with a file path. You can specify a different directory for the project PLT file with the `:plt_local_path keyword`. You can specify a different filename for the project PLT file with the `:plt_file keyword` - this is deprecated because people were using it with the old `dialyxir` to have project-specific PLTs, which are now the default. To silence the deprecation warning, specify this value as `plt_file: {:no_warn, "/myproject/mypltfile"}`.
 
 The core PLTs include a basic set of OTP applications, as well as all of the Elixir standard libraries.
-The apps included by default are `[ :erts, :kernel, :stdlib, :crypto]`.
+The apps included by default are `[:erts, :kernel, :stdlib, :crypto]`.
 
 If you don't want to include the default apps you can specify a `:plt_apps` key and list there only the apps you want in the PLT. Using this option will mean dependencies are not added automatically (see below). If you want to just add an application to the list of defaults and dependencies you can use the `:plt_add_apps` key.
 
@@ -140,8 +148,9 @@ If you want to ignore a specific dependency, you can specify it in the `:plt_ign
 #### Dependencies
 
 OTP application dependencies are (transitively) added to your PLT by default. The applications added are the same as you would see displayed with the command `mix app.tree`. There is also a `:plt_add_deps` option you can set to control the dependencies added. The following options are supported:
-  * :apps_direct - Only Direct OTP runtime application dependencies - not the entire tree
-  * :app_tree - Transitive OTP runtime application dependencies e.g. `mix app.tree` (default)
+
+  * `:apps_direct` - Only Direct OTP runtime application dependencies - not the entire tree
+  * `:app_tree` - Transitive OTP runtime application dependencies e.g. `mix app.tree` (default)
 
 
 The example below changes the default to include only direct OTP dependencies, adds another specific dependency, and removes a dependency from the list. This can be helpful if a large dependency tree is creating memory issues and only some of the transitive dependencies are required for analysis.
@@ -168,6 +177,7 @@ Explanations are available for classes of warnings by executing `mix dialyzer.ex
 #### Formats
 
 Dialyxir supports formatting the errors in several different ways:
+
   * Short - By passing `--format short`, the structs and other spec/type information will be dropped from the error message, with a minimal message. This is useful for CI environments. Includes `warning_name ` for use in explanations.
   * Dialyzer - By passing `--format dialyzer`, the messages will be printed in the default Dialyzer format. This format is used in [legacy string matching](#simple-string-matches) ignore files.
   * Raw - By passing `--format raw`, messages will be printed in their form before being pretty printed by Dialyzer or Dialyxir.
@@ -242,7 +252,7 @@ def project do
 end
 ```
 
-This file comes in two formats: `--format dialyzer` string matches (compatbile with <= 0.5.1 ignore files), and the [term format](#elixir-term-format).
+This file comes in two formats: `--format dialyzer` string matches (compatible with `<= 0.5.1` ignore files), and the [term format](#elixir-term-format).
 
 #### Simple String Matches
 

lib/dialyxir/formatter.ex

@@ -153,11 +153,11 @@ defmodule Dialyxir.Formatter do
     warnings_count = Enum.count(warnings)
     filtered_warnings_count = Enum.count(filtered_warnings)
     skipped_count = warnings_count - filtered_warnings_count
-    unnessary_skips_count = count_unnecessary_skips(filter_map)
+    unnecessary_skips_count = count_unnecessary_skips(filter_map)
 
     info(
       "Total errors: #{warnings_count}, Skipped: #{skipped_count}, " <>
-        "Unnecessary Skips: #{unnessary_skips_count}"
+        "Unnecessary Skips: #{unnecessary_skips_count}"
     )
 
     :ok

lib/dialyxir/warning.ex

@@ -6,13 +6,13 @@ defmodule Dialyxir.Warning do
   """
 
   @doc """
-  By expressing the warning that is to be matched on, error handlong
+  By expressing the warning that is to be matched on, error handling
   and dispatching can be avoided in format functions.
   """
   @callback warning() :: atom
 
   @doc """
-  The default documentation when seeing an error wihout the user
+  The default documentation when seeing an error without the user
   otherwise overriding the format.
   """
   @callback format_long([String.t()] | {String.t(), String.t(), String.t()} | String.t()) ::

lib/mix/tasks/dialyzer.ex

@@ -8,24 +8,24 @@ defmodule Mix.Tasks.Dialyzer do
 
   ## Command line options
 
-    * `--no-compile`       - do not compile even if needed.
-    * `--no-check`         - do not perform (quick) check to see if PLT needs update.
-    * `--force-check`      - force PLT check also if lock file is unchanged.
-       useful when dealing with local deps.
-    * `--ignore-exit-status` - display warnings but do not halt the VM or return an exit status code
-    * `--list-unused-filters` - list unused ignore filters
-      useful for CI. do not use with `mix do`.
-    * `--plt`              - only build the required plt(s) and exit.
-    * `--format short`     - format the warnings in a compact format.
-    * `--format raw`       - format the warnings in format returned before Dialyzer formatting
-    * `--format dialyxir`  - format the warnings in a pretty printed format
-    * `--format dialyzer`  - format the warnings in the original Dialyzer format
-    * `--quiet`            - suppress all informational messages
-
-  Warning flags passed to this task are passed on to `:dialyzer`.
-
-  e.g.
-  `mix dialyzer --unmatched_returns`
+    * `--no-compile` - do not compile even if needed
+    * `--no-check` - do not perform (quick) check to see if PLT needs update
+    * `--force-check` - force PLT check also if lock file is unchanged useful
+      when dealing with local deps.
+    * `--ignore-exit-status` - display warnings but do not halt the VM or
+      return an exit status code
+    * `--list-unused-filters` - list unused ignore filters useful for CI. do
+      not use with `mix do`.
+    * `--plt` - only build the required PLT(s) and exit
+    * `--format short` - format the warnings in a compact format
+    * `--format raw` - format the warnings in format returned before Dialyzer formatting
+    * `--format dialyxir` - format the warnings in a pretty printed format
+    * `--format dialyzer` - format the warnings in the original Dialyzer format
+    * `--quiet` - suppress all informational messages
+
+  Warning flags passed to this task are passed on to `:dialyzer` - e.g.
+
+      mix dialyzer --unmatched_returns
 
   ## Configuration
 
@@ -54,8 +54,8 @@ defmodule Mix.Tasks.Dialyzer do
 
   OTP application dependencies are (transitively) added to your project's PLT by default. The applications added are the same as you would see displayed with the command `mix app.tree`. There is also a `:plt_add_deps` option you can set to control the dependencies added. The following options are supported:
 
-  * :apps_direct - Only Direct OTP runtime application dependencies - not the entire tree
-  * :app_tree - Transitive OTP runtime application dependencies e.g. `mix app.tree` (default)
+  * `:apps_direct` - Only Direct OTP runtime application dependencies - not the entire tree
+  * `:app_tree` - Transitive OTP runtime application dependencies e.g. `mix app.tree` (default)
 
   ```
   def project do
@@ -81,11 +81,11 @@ defmodule Mix.Tasks.Dialyzer do
 
   ### Other Configuration
 
-  * `dialyzer: :plt_file` - Deprecated - specify the plt file name to create and use - default is to create one in the project's current build environmnet (e.g. _build/dev/) specific to the Erlang/Elixir version used. Note that use of this key in version 0.4 or later will produce a deprecation warning - you can silence the warning by providing a pair with key :no_warn e.g. `plt_file: {:no_warn,"filename"}`.
+  * `dialyzer: :plt_file` - Deprecated - specify the PLT file name to create and use - default is to create one in the project's current build environment (e.g. _build/dev/) specific to the Erlang/Elixir version used. Note that use of this key in version 0.4 or later will produce a deprecation warning - you can silence the warning by providing a pair with key :no_warn e.g. `plt_file: {:no_warn,"filename"}`.
 
-  * `dialyzer: :plt_local_path` - specify the plt directory name to create and use - default is the project's current build environmnet (e.g. _build/dev/).
+  * `dialyzer: :plt_local_path` - specify the PLT directory name to create and use - default is the project's current build environment (e.g. `_build/dev/`).
 
-  * `dialyzer: :plt_core_path` - specify an alternative to MIX_HOME to use to store the Erlang and Elixir core files.
+  * `dialyzer: :plt_core_path` - specify an alternative to `MIX_HOME` to use to store the Erlang and Elixir core files.
 
   * `dialyzer: :ignore_warnings` - specify file path to filter well-known warnings.
   """
@@ -98,15 +98,15 @@ defmodule Mix.Tasks.Dialyzer do
   alias Dialyxir.Dialyzer
 
   defmodule Build do
-    @shortdoc "Build the required plt(s) and exit."
+    @shortdoc "Build the required PLT(s) and exit."
 
     @moduledoc """
     This task compiles the mix project and creates a PLT with dependencies if needed.
     It is equivalent to running `mix dialyzer --plt`
 
     ## Command line options
 
-    * `--no-compile`       - do not compile even if needed.
+    * `--no-compile` - do not compile even if needed.
     """
     use Mix.Task
 
@@ -116,14 +116,14 @@ defmodule Mix.Tasks.Dialyzer do
   end
 
   defmodule Clean do
-    @shortdoc "Delete plt(s) and exit."
+    @shortdoc "Delete PLT(s) and exit."
 
     @moduledoc """
     This task deletes PLT files and hash files.
 
     ## Command line options
 
-    * `--all`       - delete also core PLTs.
+      * `--all` - delete also core PLTs.
     """
     use Mix.Task
 
@@ -361,7 +361,7 @@ defmodule Mix.Tasks.Dialyzer do
       beyond the dialyzer defaults are included. All these properties can be changed in configuration.
       (see `mix help dialyzer`).
 
-      If you no longer use the older Dialyxir in any projects and do not want to see this notice each time you upgrade your Erlang/Elixir distribution, you can delete your old pre-0.4 PLT files. ( rm ~/.dialyxir_core_*.plt )
+      If you no longer use the older Dialyxir in any projects and do not want to see this notice each time you upgrade your Erlang/Elixir distribution, you can delete your old pre-0.4 PLT files. (`rm ~/.dialyxir_core_*.plt`)
       """)
     end
   end

lib/mix/tasks/dialyzer/explain.ex

@@ -1,8 +1,8 @@
 defmodule Mix.Tasks.Dialyzer.Explain do
-  @shortdoc "Display information about dialyzer warnings."
+  @shortdoc "Display information about Dialyzer warnings."
 
   @moduledoc """
-  This task provides background information about dialyzer warnings.
+  This task provides background information about Dialyzer warnings.
   If invoked without any arguments it will list all warning atoms.
   When invoked with the name of a particular warning, it will display
   information regarding it.

mix.exs

@@ -1,10 +1,13 @@
 defmodule Dialyxir.Mixfile do
   use Mix.Project
 
+  @source_url "https://github.com/jeremyjh/dialyxir"
+  @version "1.0.0"
+
   def project do
     [
       app: :dialyxir,
-      version: "1.0.0",
+      version: @version,
       elixir: ">= 1.6.0",
       elixirc_paths: elixirc_paths(Mix.env()),
       description: description(),
@@ -18,10 +21,14 @@ defmodule Dialyxir.Mixfile do
       ],
       # Docs
       name: "Dialyxir",
-      source_url: "https://github.com/jeremyjh/dialyxir",
-      homepage_url: "https://github.com/jeremyjh/dialyxir",
+      homepage_url: @source_url,
       # The main page in the docs
-      docs: [main: "readme", extras: ["README.md"]]
+      docs: [
+        main: "readme",
+        source_url: @source_url,
+        source_ref: @version,
+        extras: ["CHANGELOG.md", "README.md"]
+      ]
     ]
   end
 
@@ -41,7 +48,7 @@ defmodule Dialyxir.Mixfile do
   defp deps do
     [
       {:erlex, ">= 0.2.6"},
-      {:ex_doc, ">= 0.0.0", only: :dev}
+      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false}
     ]
   end
 
@@ -54,8 +61,11 @@ defmodule Dialyxir.Mixfile do
         "LICENSE"
       ],
       maintainers: ["Jeremy Huffman"],
-      licenses: ["Apache 2.0"],
-      links: %{"GitHub" => "https://github.com/jeremyjh/dialyxir"}
+      licenses: ["Apache-2.0"],
+      links: %{
+        "Changelog" => "https://hexdocs.pm/dialyxir/changelog.html",
+        "GitHub" => @source_url
+      }
     ]
   end
 end

mix.lock

@@ -1,8 +1,9 @@
 %{
   "earmark": {:hex, :earmark, "1.2.6", "b6da42b3831458d3ecc57314dff3051b080b9b2be88c2e5aa41cd642a5b044ed", [:mix], [], "hexpm", "b42a23e9bd92d65d16db2f75553982e58519054095356a418bb8320bbacb58b1"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.12", "b245e875ec0a311a342320da0551da407d9d2b65d98f7a9597ae078615af3449", [:mix], [], "hexpm", "711e2cc4d64abb7d566d43f54b78f7dc129308a63bc103fbd88550d2174b3160"},
   "erlex": {:hex, :erlex, "0.2.6", "c7987d15e899c7a2f34f5420d2a2ea0d659682c06ac607572df55a43753aa12e", [:mix], [], "hexpm", "2ed2e25711feb44d52b17d2780eabf998452f6efda104877a3881c2f8c0c0c75"},
-  "ex_doc": {:hex, :ex_doc, "0.19.1", "519bb9c19526ca51d326c060cb1778d4a9056b190086a8c6c115828eaccea6cf", [:mix], [{:earmark, "~> 1.1", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.7", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "dc87f778d8260da0189a622f62790f6202af72f2f3dee6e78d91a18dd2fcd137"},
-  "makeup": {:hex, :makeup, "0.5.5", "9e08dfc45280c5684d771ad58159f718a7b5788596099bdfb0284597d368a882", [:mix], [{:nimble_parsec, "~> 0.4", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "d7152ff93f2eac07905f510dfa03397134345ba4673a00fbf7119bab98632940"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.10.0", "0f09c2ddf352887a956d84f8f7e702111122ca32fbbc84c2f0569b8b65cbf7fa", [:mix], [{:makeup, "~> 0.5.5", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "4a36dd2d0d5c5f98d95b3f410d7071cd661d5af310472229dd0e92161f168a44"},
-  "nimble_parsec": {:hex, :nimble_parsec, "0.4.0", "ee261bb53214943679422be70f1658fff573c5d0b0a1ecd0f18738944f818efe", [:mix], [], "hexpm", "ebb595e19456a72786db6dcd370d320350cb624f0b6203fcc7e23161d49b0ffb"},
+  "ex_doc": {:hex, :ex_doc, "0.23.0", "a069bc9b0bf8efe323ecde8c0d62afc13d308b1fa3d228b65bca5cf8703a529d", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "f5e2c4702468b2fd11b10d39416ddadd2fcdd173ba2a0285ebd92c39827a5a16"},
+  "makeup": {:hex, :makeup, "1.0.5", "d5a830bc42c9800ce07dd97fa94669dfb93d3bf5fcf6ea7a0c67b2e0e4a7f26c", [:mix], [{:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cfa158c02d3f5c0c665d0af11512fed3fba0144cf1aadee0f2ce17747fba2ca9"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.15.0", "98312c9f0d3730fde4049985a1105da5155bfe5c11e47bdc7406d88e01e4219b", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "75ffa34ab1056b7e24844c90bfc62aaf6f3a37a15faa76b07bc5eba27e4a8b4a"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"},
 }