[erlang-questions] Documentation Format Changes (erldocs)

[Dale Harvey]

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>&nbsp;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

[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

_______________________________________________
erlang-questions mailing list
erlang-q...@erlang.org
http://erlang.org/mailman/listinfo/erlang-questions

[Lukas Larsson]

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" <da...@arandomurl.com>
To: "erlang-questions" <erlang-q...@erlang.org>
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> &nbsp; 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

_______________________________________________

[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

[Dale Harvey]

It looks like a lot more of the documentation has moved over arity format which requires a source code lookup to find the correct function signature.

Does anyone know how given a the path to a .erl file, a function and an arity I can find a human readable function signature from the type specs, looking over the current edoc / docbuilder source I am not finding much

https://github.com/erlang/otp/blob/master/lib/stdlib/src/lists.erl#L1136

find_function_signature("otp_src_R14B04/lib/stdlib/src/lists.erl", "all", 2) ->
    "all(Pred, List) -> boolean()".

If anyone could give more insight into why this information isnt embedded into the intermediary xml format it would be nice, having to do a source code lookup makes the intermediary xml format pointless, it would be hugely easier to generate documentation directly from a single source of truth(the source files) if it wasnt for the fact that half the information needed is not included in the source files, for example the @doc annotation for lists:all

      <fsummary>Return true if all elements in the list satisfy<c>Pred</c></fsummary>

is not anywhere in
https://github.com/erlang/otp/blob/master/lib/stdlib/src/lists.erl#L1136


I have offered this before but erldocs is open source, it was built before the current attempt at a search as you type implementation on the erlang.org site, and is still more complete (it works offline, it doesnt use iframes and therefore is linkable and searchable) if there is anything I can do to get it 'blessed' in a way that it doesnt get broken during every erlang release then I will be happy to do it. It is reasonably popular (around 9k visits the average month) and given the amount of people that contact me when its late to update or broken I think its beneficial for the community for it not to be so.


Cheers
Dale

[Anthony Molinaro]

As an active user of erldocs I'd like to +1 anything which will make this work again.  I have to use old docs just so I can see the right information.  Maybe if enough people call out that they would like to see this fixed we can get a fix for the next release.

-Anthony

[Gordon Guthrie]

I second that emotion

--
Gordon Guthrie
CEO hypernumbers

http://hypernumbers.com
t: hypernumbers
+44 7776 251669