edoc: commenting multiple patterns of a function

Vincent de Phily <>
Tue Jul 21 20:37:45 CEST 2009


Hi list,

not a big issue but it always bugged me: how do you add edoc comments to a 
function depending on its pattern match ? eg:

-behavior(gen_server).
...
% @doc Modify counter.
handle_cast({inc, N}, Count) -> {noreply, Count + N};
% @doc Reset counter.
handle_cast(reset, Count) -> {noreply, 0};
handle_cast(Other, Count) -> {stop, {api_violation, Other}, 0}.

In this example, the edoc-generated file will just say "Modify counter", 
ignoring that the function can also "Reset counter".

What I hoped to find in the doc, was the two @doc comments, ideally with the 
corresponding pattern (it would be great if that pattern could be specified 
in the docs).

I could add all the documentation in the first @doc instance, but it'll be 
horribly unreadable (especially in a gen_server with numerous large handle_* 
functions).
Or I could use a generic "handles gen_server casts, see source for possible 
casts", but it makes the edoc a bit useless (I allready know what the 
behavior callbacks do, no need to read project-specific doc).

Any thoutghs ?

-- 
Vincent de Phily
Mobile Devices
+33 (0) 666 301 306
+33 (0) 142 119 325

Warning
This message (and any associated files) is intended only for the use of its
intended recipient and may contain information that is confidential, subject
to copyright or constitutes a trade secret. If you are not the intended
recipient you are hereby notified that any dissemination, copying or
distribution of this message, or files associated with this message, is
strictly prohibited. If you have received this message in error, please
notify us immediately by replying to the message and deleting it from your
computer. Any views or opinions presented are solely those of the author
 and do not necessarily represent those of 
the
company. Although the company has taken reasonable precautions to ensure no
viruses are present in this email, the company cannot accept responsibility
for any loss or damage arising from the use of this email or attachments.


More information about the erlang-questions mailing list