Erlang eDoc: Function doc comments don't show up in output

I'm trying climbing the learning curve toward Erlang best practices; just now integrating eDoc into my workflow.

This works for me:

%%% --------------------------------------------------------------------
%%% @author Lloyd R. Prentice
%%% @copyright 2011 Lloyd R. Prentice
%%% @doc Yada yada
%%%      ...
%%% @end
%%% --------------------------------------------------------------------

Everything shows up in the docs as I'd expect.

But this doesn't:

%% Return a list of reserved item types
item_types() ->
        ....

I'm expecting to see a list of functions and doc comments in the eDoc output. But, no show.

I've scoured eDoc documentation, looked for examples and tutorials on the web, but I can't see what I'm doing wrong.

Can anyone h开发者_StackOverflow中文版elp?

Many thanks,

LRP

If you called edoc correctly, based on your example I would expect to see the outline of your module along with the function names but not the documentation for each function.

Just above each exported function you will need to add a @spec tag and/or a -spec tag along with a @doc tag. You can see these explained here and here. If you have (or are targeting) a recent version of erlang (>14B02?) edoc will read -spec information, otherwise you'll need to use @spec.

For example:

%% @spec item_types() -> list()
%% @doc Return a list of reserved item types.
item_types() ->

or

-spec item_types() -> list().
%% @doc Return a list of reserved item types.
item_types() ->

Note the . at the end of the -spec.

First of all, only exported functions show up in the generated documentation (unless you pass the option 'private' to EDoc, telling it to show all non-exported functions as well). So if you don't have a declaration like:

  -export([item_types/0]).

in your module, the function will not be shown.

Second, you must begin the comment above the function declaration with @doc, as in:

  %% @doc Return a list of reserved item types
  item_types() ->

A comment without an @-tag is just a comment, and is ignored by EDoc.

From the documentation:

A tag must be the first thing on a comment line, except for leading '%' characters and whitespace.

Could this be the reason?