erl_doc_chunks
is a Mix compiler that generates docs chunks for Erlang files.
This project is a reminder that Mix works really well for building Erlang codebases too. I'm hoping things shown hear will come to Rebar & EUnit soon too!
See examples/foo
project which is an Erlang project built with Mix. Also see
examples/bar
which is an Elixir project that uses foo
.
-
Create a Mix project for your Erlang codebase and install
erl_doc_chunks
:$ mix new foo
It is important that the compiler is added last, it needs to run after the Erlang compiler.
# mix.exs defmodule Foo.MixProject do use Mix.Project def project do [ app: :foo, version: "0.1.0", elixir: "~> 1.10", deps: deps(), compilers: Mix.compilers() ++ [:erl_doc_chunks] ] end defp deps do [ {:erl_doc_chunks, github: "wojtekmach/erl_doc_chunks"} ] end end
-
Document your Erlang file with Markdown:
%% @doc %% The foo module. -module(foo). -export([hello/0, bar/0]). %% @doc %% Returns a hello. %% %% ## Examples %% %% iex> :foo.hello() %% :world2 hello() -> world. bar() -> bar.
The choice of Markdown is totally arbitrary, any other documentation format would work.
-
You can now access the docs from the IEx shell:
$ iex -S mix iex(1)> h :foo :foo The foo module.
As well as from the Erlang shell:
$ erl -pa _build/dev/lib/foo/ebin 1> h(foo). foo The foo module. ok
-
You can write an ExUnit test case and use the doctest feature:
# test/foo_test.exs defmodule :foo_test do use ExUnit.Case, async: true doctest :foo end
$ mix test 1) doctest :foo.hello/0 (1) (:foo_test) test/foo_test.exs:3 Doctest failed doctest: iex> :foo.hello() :world2 code: :foo.hello() === :world2 left: :world right: :world2 stacktrace: src/foo.erl:11: :foo (module) Finished in 0.02 seconds (0.02s async, 0.00s sync) 1 doctest, 1 failure
Doctest support requires a tiny change to the Elixir.
Copyright (c) 2021 Wojtek Mach
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.