Erlang eDoc: комментарии к функциям не отображаются в выходных данных

Question

Я пытаюсь подняться по кривой обучения в сторону лучших практик Эрланга; только сейчас интегрирую eDoc в мой рабочий процесс.

Это работает для меня:

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

В документах все отображается так, как я ожидал.

Но это не так:

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

Я ожидаю увидеть список функций и комментариев к документу в выводе eDoc. Но не показывать.

Я просмотрел документацию по eDoc, искал в Интернете примеры и учебные пособия, но не вижу, что я делаю неправильно.

Может кто-нибудь помочь?

Большое спасибо,

LRP

Answer 1

Если вы правильно вызвали edoc, основываясь на вашем примере, я ожидаю увидеть схему вашего модуля вместе с именами функций, но не документацию для каждой функции.

Чуть выше каждой экспортируемой функции вам нужно будет добавить тег @spec и / или тег -spec вместе с тегом @doc. Вы можете увидеть эти объясненные здесь и здесь . Если у вас есть (или вы используете таргетинг), последняя версия erlang (> 14B02?) Edoc будет читать -spec информацию, в противном случае вам придется использовать @spec.

Например:

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

или

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

Обратите внимание на . в конце -spec.

Answer 2

Прежде всего, только сгенерированные функции отображаются в сгенерированной документации (если вы не передадите опцию 'private' в EDoc, сообщив ей также показывать все неэкспортированные функции).Поэтому, если в вашем модуле нет объявления вроде:

  -export([item_types/0]).

, функция не будет показана.

Во-вторых, вы должны начать комментарий над объявлением функции с @doc, как в:

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

Комментарий без тега @ является просто комментарием и игнорируется EDoc.

Answer 3

Из документации :

Тег должен быть первым в строке комментария, за исключением начальных символов '%' и пробелов.

Может ли это быть причиной?