The New and Improved edoc

[Richard Carlsson]

On Tue, 24 Feb 2004, Ulf Wiger wrote:

> I have a question regarding the new and improved edoc
> (apart from "when will it appear in Jungerl?")

As soon as someone puts it there? Go ahead - if anyone adds
something to it, I can pick it up and include it in the
"official version".

Sadly, I have been too bogged down with More Important Things
to do the last couple of months, so I've hardly touched the
code since Christmas.

> When documenting behaviours, one wants to specify the required
> callback functions in a manner similar to the gen_server documentation.
>
> How does one do that? Does edoc offer a standard way of doing it, or
> will I have to "fake it" in the module documentation?

Ideally, there should be facilities for grouping things (functions,
etc.) under different headings. But that's for functions that are
actually defined in the module.

The new edoc already documents that a module implements a particular
behaviour (if it contains "-behaviour(xxx).") It could also be made to
recognize the behaviour_info/1 function and present the callback
functions automatically. But the only information available is the
names and arities of the callbacks. The question is how to document
the callbacks in more detail.

A straightforward way of doing it is of course to provide a dummy
callback module, and refer to that for the documentation. If you don't
like that solution, you'll just have to document the callbacks in a
"hard-coded" manner using HTML in the edoc comments, for now anyway.

	/Richard


Richard Carlsson (richardc@REDACTED)   (This space intentionally left blank.)
E-mail: Richard.Carlsson@REDACTED	WWW: http://user.it.uu.se/~richardc/
 "Having users is like optimization: the wise course is to delay it."
   -- Paul Graham