[erlang-questions] Documentation Format Changes (erldocs)

[James Churchman]

I have no idea personally, only a guess but ;

All this type information in the xml files is duplicate now... the specs contain not only the function signature but also the types of the inputs.

Specs are relatively recent addition, so the original creation of the xml documentation files probably predate the addition of specs to erlang. It might be that ErlDocs.com is incapable of parsing the specs out of the source and turning that into the documentation type information.

The official erlang site appears to have it correct http://www.erlang.org/doc/man/lists.html#keymerge-3 

So probably there is an effort to remove duplicate data from documentation xml files, reducing double updates along with the fact that the xml docs are just data, i don't believe they are machine checked for accuracy..

One other thing tho, why is the separate xml file preferred instead of the edoc inline notation, just to keep the two things separate and keep the code more readable? 

Anyhow thats my guess!

James


On 12 Jun 2011, at 01:25, Dale Harvey wrote:

> 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#L299 is 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/20110612/c52a19d6/attachment.htm>