[erlang-questions] Documentation Format Changes (erldocs)

[Dale Harvey]

It seems like if we need to cross reference the documentation xml with the
type annotations in the source, what is the point in having docbuilder
generate intermediary xml (with a constantly changing and non documented
schema) at all? we could just generate the output format directly from the
source.

the only reason I dont do now is that a good chunk of the documentation (the
important modules like lists etc) are only available in the xml format and
not in the source.

the old documentation used to take edoc formatted type annotations and embed
them into the generated xml (like shown above). the format may be different
but I cant see why that isnt far better than cross referencing stuff.

Cheers
Dale

On 13 June 2011 11:03, Lukas Larsson <lukas.larsson@REDACTED>wrote:

> Hi Dale!
>
> All of the documentation is right now being reworked to generate type
> information from the specs in the source instead of manually writing them.
> <name name= "keymerge" arity= "3" /> tells docbuilder (I think) to generate
> the type description from the specs instead of the XML file. If you dig
> around in the source code of docbuilder/edoc there should be functions
> somewhere there which you can use to generate type information for erldocs.
>
> Lukas
> ----- Original Message -----
> From: "Dale Harvey" <dale@REDACTED>
> To: "erlang-questions" <erlang-questions@REDACTED>
> Sent: Sunday, 12 June, 2011 02:25:29 GMT +01:00 Amsterdam / Berlin / Bern /
> Rome / Stockholm / Vienna
> Subject: [erlang-questions] Documentation Format Changes (erldocs)
>
>
> Hey all
>
> I was wondering about the changes in the format documentation sources, in
> the last release I noticed a few function definitions changed from
>
> <name> keymember(Key, N, TupleList) -> boolean() </name>
> <fsummary> Test for membership of a list of tuples </fsummary>
> <type>
> <v> Key = term() </v>
> <v> N = 1..tuple_size(Tuple) </v>
> <v> TupleList = [Tuple] </v>
> <v>   Tuple = tuple() </v>
> </type> to
>
> <name name= "keymerge" arity= "3" />
> <fsummary> Merge two key-sorted lists of tuples </fsummary>
> <type_desc variable= "N" > 1..tuple_size(Tuple) </type_desc>
> https://github.com/erlang/otp/blob/dev/lib/stdlib/doc/src/lists.xml#L299is the source for these changes, somehow the recent erlang documention (
> http://www.erlang.org/doc/man/lists.html#keymerge-3 ) shows the full
> parameter list information and I am quite confused at how that can be
> derived from the source xml.
>
> I was also just curious about the reason for the change and what was
> planned for going forward
>
> since
> http://erldocs.com/R14B03/stdlib/lists.html?i=0&search=lists%20keymerge#keymerge/3
> is a lot less useful than
> http://erldocs.com/R14B02/stdlib/lists.html?i=0&search=lists%20keymerge#keymerge/3
>
> Cheers, good work on the new release
> Dale
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20110622/23281cc4/attachment.htm>