Documenting functions with multiple arity

Questions / Help
1

I am writing a small little lib and I’m undecided on how to effectively document the public functions where there are multiple arity versions.

For example

def new(arg1),       do: %{a: arg1}
def new(arg1, arg2), do: %{a: arg1, b: arg2}

Now this is a little contrived but I wondered what might be the best way to document these two functions. In the past I have put a @doc on each function and just gone with some duplication in the doc wording. However in my case arg1 is expected to be within a range of values, lets say one of these two tuples :abc or :xyz. At this point I’m now having to document the accepted range in docs for both functions and I feel this is now too much duplication.

Maybe the approach is incorrect and I should be using a default param like so

def new(arg1, arg2 \\ ""), do: %{a: arg1, b: arg2}

Anyway, I am hoping someone may have figured out the desired approach for this kind of situation and has the sliver bullet answer :smile:

3 Likes
2

If they truly do the same thing but with just a default argument then make it the same function with a default, else keep it separate and @doc each of them, even if duplication. :slight_smile:

2 Likes
3

In this case the functions actually ended up doing the same thing so just used a default argument like you mentioned.

Shame that there is a scenario here whereby duplicating docs has to happen, maybe there could be some form of enhancement here that could ease this moving forwards. Perhaps some kind of document reuse based on function names, tags or something else.

1 Like
4

Maybe take a look at how Ecto does it? They just reference the other function and describe the differences. For instance https://hexdocs.pm/ecto/Ecto.Repo.html#c:get/3 and get!/3. Also Changeset.validate_change/3 and Changeset.validate_change/4.

2 Likes