Misc doc changes

.formatter.exs

@@ -1,4 +1,4 @@
 # Used by "mix format"
 [
-  inputs: ["mix.exs", "{config,lib,test}/**/*.{ex,exs}"]
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
 ]

.gitignore

@@ -7,7 +7,7 @@
 # The directory Mix downloads your dependencies sources to.
 /deps/
 
-# Where 3rd-party dependencies like ExDoc output generated docs.
+# Where third-party dependencies like ExDoc output generated docs.
 /doc/
 
 # Ignore .fetch files in case you like to edit your project deps locally.
@@ -22,5 +22,8 @@ erl_crash.dump
 # Ignore package tarball (built via "mix hex.build").
 toml-*.tar
 
-# Ignore generated benchmark output
+# Temporary files, for example, from tests.
+/tmp/
+
+# Ignore generated benchmark output.
 /bench/output/

LICENSE

@@ -174,30 +174,3 @@
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "{}"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2012 Plataformatec
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
-
-

README.md

@@ -1,12 +1,20 @@
 # TOML for Elixir
 
 [![Master](https://travis-ci.com/bitwalker/toml-elixir.svg?branch=master)](https://travis-ci.com/bitwalker/toml-elixir)
-[![Hex.pm Version](http://img.shields.io/hexpm/v/toml.svg?style=flat)](https://hex.pm/packages/toml)
+[![Hex Version](https://img.shields.io/hexpm/v/toml.svg?style=flat)](https://hex.pm/packages/toml)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg?style=flat)](https://hexdocs.pm/toml/)
+[![Total Download](https://img.shields.io/hexpm/dt/toml.svg?style=flat)](https://hex.pm/packages/toml)
+[![License](https://img.shields.io/hexpm/l/toml-elixir.svg?style=flat)](https://github.com/bitwalker/toml-elixir/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/bitwalker/toml-elixir.svg?style=flat)](https://github.com/bitwalker/toml-elixir/commits/master)
 
-This is a TOML library for Elixir projects. It is compliant with version 0.5.0 of the
-[official TOML specification](https://github.com/toml-lang/toml). You can find a
-brief overview of the feature set below, but you are encouraged to read the full
-spec at the link above (it is short and easy to read!).
+<!-- MDOC !-->
+
+This is a TOML library for Elixir projects.
+
+It is compliant with version 0.5.0 of the [official TOML
+specification](https://github.com/toml-lang/toml). You can find a brief
+overview of the feature set below, but you are encouraged to read the full spec
+at the link above (it is short and easy to read!).
 
 ## Features
 
@@ -90,7 +98,7 @@ the same base type (e.g. integer and string respectively in the examples given).
 Certain features of TOML have implementation-specific behavior:
 
 - `-inf`, `inf`, and `+inf` are all valid infinity values in TOML.
-  In Erlang/Elixir, these don't have exact representations. Instead, by convention, 
+  In Erlang/Elixir, these don't have exact representations. Instead, by convention,
   `:infinity` is used for positive infinity, as atoms are always larger than integers
   when using comparison operators, so `:infinity > <any integer>` will always be true.
   However, negative infinity cannot be represented, as numbers are always considered smaller
@@ -99,7 +107,7 @@ Certain features of TOML have implementation-specific behavior:
   in comparisons/sorting/etc.
 - `-nan`, `nan`, and `+nan` are all valid NaN (not a number) values in TOML. In Erlang/Elixir,
   NaN is traditionally represented with `:nan`, but there is no representation for negative NaN,
-  and no API actually produces `:nan`, instead invalid numbers typically raise errors, in the typical 
+  and no API actually produces `:nan`, instead invalid numbers typically raise errors, in the typical
   spirit of "let it crash" in the face of errors. For purposes of preserving type information though,
   we use the `:nan` convention, and `:negative_nan` for -NaN. You will need to take care to deal with
   these values manually if the values need to be preserved.
@@ -180,7 +188,7 @@ expected '\n', but got 'b' in nofile on line 2:
 Support for extending value conversions is provided by the `Toml.Transform`
 behavior. An example is shown below:
 
-Given the follwing TOML document:
+Given the following TOML document:
 
 ``` toml
 [servers.alpha]
@@ -201,7 +209,7 @@ end
 
 defmodule IPStringToCharlist do
   use Toml.Transform
-  
+
   def transform(:ip, v) when is_binary(v) do
     String.to_charlist(v)
   end
@@ -210,7 +218,7 @@ end
 
 defmodule CharlistToIP do
   use Toml.Transform
-  
+
   def transform(:ip, v) when is_list(v) do
     case :inet.parse_ipv4_address(v) do
       {:ok, address} ->
@@ -225,7 +233,7 @@ end
 
 defmodule ServerMapToList do
   use Toml.Transform
-  
+
   def transform(:servers, v) when is_map(v) do
     for {name, server} <- v, do: struct(Server, Map.put(server, :name, name))
   end
@@ -323,13 +331,25 @@ level = "info"
 format = "[$level] $message \n"
 ```
 
+<!-- MDOC !-->
+
 ## Roadmap
 
 - [x] Add benchmarking suite
 - [x] Provide options for converting keys to atom, similar to Jason/Poison/etc.
 - [ ] Optimize lexer to always send offsets to decoder, rather than only in some cases
 - [ ] Try to find pathological TOML files to test
 
-## License
+## Copyright and License
+
+Copyright (c) 2018 Paul Schoenfelder
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)
 
-This project is licensed Apache 2.0, see the `LICENSE` file in this repo for details.
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

lib/toml.ex

@@ -1,5 +1,10 @@
 defmodule Toml do
-  @moduledoc File.read!(Path.join([__DIR__, "..", "README.md"]))
+  @external_resource "README.md"
+
+  @moduledoc "README.md"
+             |> File.read!()
+             |> String.split("<!-- MDOC !-->")
+             |> Enum.fetch!(1)
 
   @type key :: binary | atom | term
   @type opt ::
@@ -25,16 +30,16 @@ defmodule Toml do
       * `:atoms` - converts keys to atoms with `String.to_atom/1`
       * `:atoms!` - converts keys to atoms with `String.to_existing_atom/1`
       * `(key -> term)` - converts keys using the provided function
-      
+
     * `:transforms` - a list of custom transformations to apply to decoded TOML values,
       see `c:Toml.Transform.transform/2` for details.
-      
+
   ## Decoding keys to atoms
 
   The `:atoms` option uses the `String.to_atom/1` call that can create atoms at runtime.
   Since the atoms are not garbage collected, this can pose a DoS attack vector when used
   on user-controlled data. It is recommended that if you either avoid converting to atoms,
-  by using `keys: :strings`, or require known keys, by using the `keys: :atoms!` option, 
+  by using `keys: :strings`, or require known keys, by using the `keys: :atoms!` option,
   which will cause decoding to fail if the key is not an atom already in the atom table.
 
   ## Transformations
@@ -45,7 +50,7 @@ defmodule Toml do
   that all addresses are usable right away, and that validation of those addresses is done as
   part of decoding the document.
 
-  Keep in mind that transforms add additional work to decoding, which may result in reduced 
+  Keep in mind that transforms add additional work to decoding, which may result in reduced
   performance, if you don't need the convenience, or the validation, deferring such conversions
   until the values are used may be a better approach, rather than incurring the overhead during decoding.
   """

mix.exs

@@ -61,16 +61,21 @@ defmodule Toml.MixProject do
     [
       files: ["lib", "mix.exs", "README.md", "LICENSE"],
       maintainers: ["Paul Schoenfelder"],
-      licenses: ["Apache 2.0"],
+      licenses: ["Apache-2.0"],
       links: %{"GitHub" => @source_url}
     ]
   end
 
   defp docs do
     [
-      main: "Toml",
+      extras: [
+        LICENSE: [title: "License"],
+        "README.md": [title: "Overview"]
+      ],
+      main: "readme",
       source_url: @source_url,
-      source_ref: @version
+      source_ref: @version,
+      formatters: ["html"]
     ]
   end
 

test/fixtures/toml-test/valid/comments-everywhere.toml

@@ -7,7 +7,7 @@
 [group] # Comment
 answer = 42 # Comment
 # no-extraneous-keys-please = 999
-# Inbetween comment.
+# In between comment.
 more = [ # Comment
   # What about multiple # comments?
   # Can you handle it?