[erlang-questions] Documentation Format Changes (erldocs)

[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

On Oct 11, 2011, at 10:53 AM, Dale Harvey <dale@REDACTED> wrote:

> 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
> 
> On 22 June 2011 16:45, Dale Harvey <dale@REDACTED> wrote:
> 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#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
> 
> 
> _______________________________________________
> 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/20111011/6f9d0553/attachment.htm>