edoc question

[dda]

Richard,

Thank you for the info. I heard yesterday about the @headerfile tag,
but this brought its own problems:

20> edoc:file("src/mb.erl").
src/test.hrl: warning: documentation before function definitions is
ignored by @headerfile
src/encodings.hrl: warning: documentation before function definitions
is ignored by @headerfile
[...]
ok

I put the
%% @headerfile "test.hrl"
[...]
right after the -include("...hrl") directives. Doesn't seem to work.
The edoc tags I put in the .hrl files were the same as in .erl files
[@spec, @doc, @see etc], and someone mentioned the set of allowed tags
in .hrl may be more restricted. Any thoughts?

-- 
Didier

On 8/22/06, Richard Carlsson <richardc@REDACTED> wrote:
> dda wrote:
> > I have a module with a main .erl file and some header .hrl files. I
> > added nice edoc tags, but I can't find a way to make edoc include all
> > the hard work I put in documenting the code in the header files; the
> > help in the .erl file shows up, not the rest...
>
> Comments in header files are not automatically available to edoc.
> There are several reasons for this: first, it would cause
> duplication of the documentation (in each module that includes
> the header); second, the place where the -include(...) directive
> occurs is not necessarily where the information from the header
> file should be "inserted"; and third, it would require that you
> told edoc the exact include-path to be used for compilation of
> the module, so it could find the header files (which are not
> always in the same directory as the source file).
>
> There is however an experimental, as yet undocumented tag,
> @headerfile "foo.hrl" that you can try out. It explicitly
> includes tags from a header file at the place where the tag
> occurs. It will probably be made an official tag, so I think
> it's fairly safe to start using.
>
>         /Richard