Finitomata :: First Class Documentation

I have already introduced the finitomata library, yet another implementation of Finite Automata. The main reason I’ve decided to climb the low hill that has not been yet conquered by lazy developers only, was I‌ felt like DSL‌ does not fit well the main purpose of FSM declaration. It’s not …ahem… declarative. The FSM‌ is best described with a diagram, not with a plain English text.

Mambie

This is Mambie, by the way. He is 31 and he happily lives in Valencia zoo. He has nothing to do with finite automata at all, but look, how declarative he is. Anyway.

I‌ wanted FSM implementation to be as easy and succinct as possible. That’s why I have chosen PlantUML syntax to declare it. Later I was given an advise to support Mermaid as well.

The huge advantage of supporting Mermaid is that it can be natively embedded into library documentation. Actually, ex_doc can do way more of a cool stuff rather than the regular user (read: me) could ever imagine. It natively supports admonition blocks, KaTeX math expressions, Vega-Lite plots, and, yes, Mermaid graphs.

It’s all possible with introducing before_closing_body_tag keyword parameter for docs section in mix.exs file and implementing the respective handler as shown below (the excerpt is taken from ex_doc docs.)

docs: [
  # ...
  before_closing_body_tag: &before_closing_body_tag/1
]

# ...

defp before_closing_body_tag(:html) do
  """
  <!-- HTML injected at the end of the <body> element -->
  """
end

defp before_closing_body_tag(_), do: ""

That said, I was able to generate FSM diagrams directly in the documentation of the generated FSM implementation.

defmodule MyFSM do
  @moduledoc "FSM implementation for 3-state conditional flow"

  @fsm """
  s1 --> |to_s2| s2
  s1 --> |to_s3| s3
  """

  use Finitomata, {@fsm, Finitomata.Mermaid}
end

The above code produces the following documentation

FSM drawn with Mermaid

Happy rich documenting!