[erlang-questions] Documentation Format Changes (erldocs)

Wed Oct 12 10:45:31 CEST 2011

I second that emotion

On 12 October 2011 01:17, Anthony Molinaro <anthonym@REDACTED>wrote:

> 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>
> 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>
> 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
> <http://erlang.org>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>
> 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>
>> 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>dale@REDACTED>
>>> To: "erlang-questions" < <erlang-questions@REDACTED>
>>> 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>
>>> 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>
>>> 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>
>>> 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>
>>> 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>erlang-questions@REDACTED
>>>  <http://erlang.org/mailman/listinfo/erlang-questions>
>>> http://erlang.org/mailman/listinfo/erlang-questions
>>>
>>
>>
> _______________________________________________
> 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
>
>


-- 
Gordon Guthrie
CEO hypernumbers

http://hypernumbers.com
t: hypernumbers
+44 7776 251669
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20111012/09caee8a/attachment.htm>