Erlang docs

Alexey Nikitin

SPb Fprog meetup

29 October 2018

About me

tank-bohr

tank_bohr

EDoc is the Erlang program documentation generator. Inspired by the Javadoc
tool for the Java programming language, EDoc is adapted to the conventions
of the Erlang world, and has several features not found in Javadoc.

Richard Carlsson

Doclet

Ulf Wiger

Edown

Edoc

Ex Doc

2003

Doctests

defmodule CrispyRobot do
  @doc """
  ## Examples

      iex> CrispyRobot.sqr(5)
      26

  """
  def sqr(x) do
    x * x
  end
end

defmodule CrispyRobotTest do
  use ExUnit.Case

  doctest CrispyRobot
end

$ mix test
Compiling 1 file (.ex)


  1) doctest CrispyRobot.sqr/1 (1) (CrispyRobotTest)
     test/crispy_robot_test.exs:3
     Doctest failed
     code:  CrispyRobot.sqr(5) === 26
     left:  25
     right: 26
     stacktrace:
       lib/crispy_robot.ex:5: CrispyRobot (module)



Finished in 0.03 seconds
1 doctest, 1 failure

Randomized with seed 50281

EEP 48

Documentation storage and format

Interchange File Format

BEAM Chunks

  • Attr - module attributes, in ETF

  • CInf - compilation info, in ETF
  • Dbgi - dubug info, in ETF
  • ExpT - functions exported by module
  • ImpT - external functions used by module
  • LocT - local functions
  • AtU8 - atoms
  • Line - source code line table
  • Code - the actual bytecode
beam_lib:chunks(PathToBeam,
    ["Attr", "CInf", "Dbgi", "ExpT"]).
DocsChunkData = term_to_binary(Docs, [compressed]),
ExtraChunks = [{<<"Docs">>, DocsChunkData}],
compile:file(Src, [{extra_chunks, ExtraChunks}]).

docsh

Links

  • http://erlang.org/doc/apps/edoc/users_guide.html
  • https://github.com/uwiger/edown/
  • https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html#doctests
  • https://hexdocs.pm/ex_doc/readme.html
  • http://erlang.org/eep/eeps/eep-0048.html
  • https://github.com/erszcz/docsh
  • https://github.com/tank-bohr/eep48

Q?

Made with Slides.com