edoc - how to set up links?
Richard Carlsson
richardc@REDACTED
Thu Sep 15 17:24:08 CEST 2005
Ulf Wiger (AL/EAB) wrote:
> Looking at some generated edoc files, I'm wondering
> how one is supposed to set up working references to
> e.g. OTP's html pages.
>
> Per default, edoc creates references to http://www.erlang.org/edoc/doc/
> etc., but those don't seem to work.
Well, that was just a sort of hopeful guess that I might be able to
convince the OTP folks to generate edoc files for all standard libraries
and put it up at a default location. Come to think about it, it might
have worked better if I had actually told them about this bold and
cunning plan...
> It also has a utility function,
> edoc_lib:find_doc_dirs(), that searches the code path for doc/ directories
> relative to the ebins. For the doc directories to count, they must contain
> an 'edoc-info' file, but none of the OTP applications, at least in R10B-2
> (or the latest commercial build) have such files, as far as I can tell.
>
> Is there a generally accepted, or at least recommended, procedure?
Perhaps you can't call it a "procedure", but you can easily generate
the docs for an application, like this:
Eshell V5.5 (abort with ^G)
1> edoc:application(kernel).
2> edoc:application(stdlib).
3> ...
(Then have a look in lib/<app-dir>/doc/.)
Of course, there's no actual edoc markup in those library files,
but at least you get a list of modules and their functions (and
often you get good usage hints from the parameter names).
If your own source files actually contain cross-references between
applications, you need to generate the docs twice to make sure you
get all the references right.
I meant to automate this even further, together with some nice
index page generation, but I didn't find the time. However,
it should already be somewhat usable as it is.
/Richard
PS. I've actually done a little edoc hacking lately, so perhaps this
stuff will also be improved in the somewhat near future. One thing is
already done: automatic paragraph breaking - no need for <p>...</p>!
More information about the erlang-questions
mailing list