Looking for advice how to do inline docs for events of a LiveView

Phoenix Forum Chat / Discussions
,
1

I am interested in providing some inline docs for my LiveView events, but if I try the following I’ll get yelled at:

redefining @doc attribute previously set at line 63.

Please remove the duplicate docs. If instead you want to 
override a previously defined @doc, attach the @doc attribute 
to a function head (the function signature not followed 
by any do-block).

When doing something like:

  @doc """
  Some helpful inline docs about unarchive...
  """
  def handle_event("unarchive", %{"id" => id}, socket) do
    # code
  end

  @doc """
  Some helpful inline docs about archive...
  """
  def handle_event("archive", %{"id" => id}, socket) do
    # code
  end

My question: How are other people documenting events like this inside a LiveView or LiveComponent?

2 Likes
2

I don’t think that’s a good approach. As hinted by the warning @doc is per function, not per function head. Also usually callback implementations are not documented to start with.

What you’re trying to document is not the function, but the API between the client and the server. This is much closer to http documentation like e.g. swagger, which also depends on the http request much rather than the function handling it. I’m not aware of anything similar in that space for liveview though.

2 Likes
3

Thanks for the feedback.

I struggle with the soft LiveView/LiveCompoent event contracts and am constantly trying to improve my documentation around this area.

Also looking at Surface but all my clients are vanilla LiveView so hoping for a better plan. :man_shrugging:

4

Accumulating doc annotations would be great.
It makes a lot of sense to increase code readability using contextual comments.
# improving overall documentation at the same time