How to use a fuction inside its docs?

Questions / Help
,
1

I want to nicely visualise FSMs in my documentation.
Ex_doc can use mermaid now, so I wanted to automate the process somehow.
I’d like to do this:

  @doc """
  #{Util.Fsm.mermaid(@states, @commands, &transition/2)}
  """
  def transition(state, command), do: ...

The idea is that Util.Fsm.mermaid takes the transition function and converts them into a mermaid state transition diagram.
However, that is not possible because the @doc is evaluated at compile time before that function is defined.
It is a chicken and egg problem.

How can I work around that?

Is there a way to first compile the module and then extend the documentation of that particular function?

Or is there a trick that defers computing the entire @doc after the module is compiled?

Or maybe some other magic trick?

3 Likes
2

You cannot use functions of a module at compile time of said module. There may be the option to updated the beam chunk out of band, but I’d imagine this to cause issues elsewhere.

Another option would be a slim wrapper, where you add the documentation, but push all the implementation to a different module.

3 Likes