[erlang-questions] Documentation Format Changes (erldocs)

[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.orgsite, 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#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/20111011/f380fabf/attachment.htm>