document arity logic