[erlang-questions] Re: What about making sense?

[Joe Armstrong]

On Fri, Feb 19, 2010 at 4:33 PM, Michael Richter <ttmrichter@REDACTED> wrote:
> On 19 February 2010 22:04, Steve Davis <steven.charles.davis@REDACTED>wrote:
>
>> I somewhat disagree with this analysis...
>>
>> On Feb 19, 2:30 am, Michael Richter <ttmrich...@REDACTED> wrote:
>> > I think that is the failing of Erlang documentation at this point.  It's
>> not
>> > in tutorial-level information -- there's plenty of that and of very high
>> > quality indeed (courtesy of Armstrong and Cesarini & Thompson).  There's
>> > more of it on the way.  It's not in the reference-level information.
>>  What's
>> > there isn't ideal nor is it ideally organized but it's OK.  Better than
>> some
>> > languages, worse than others.  What's missing is information like
>> overviews
>> > of the available libraries (or "applications" in Erlang-speak), what they
>> do
>> > and a general idea of how to use them.
>>
>> If you start at the front page of the existing docs and follow the
>> advice given in those very first paragraphs, you won't go far wrong.
>>
>> http://www.erlang.org/doc/
>
>
> I do not see anything there which gives guidance on how to use dialyzer,
> edoc and typer together in the same source file.  On the subtle, vaguely
> incompatible differences in notation between these three.  Did I miss
> something?

No - you are absolutely correct. The dialyzer, edoc etc. are fine tools used
individually - but they do not play together well. Nor do inline @spec
etc in the
erlang code play well with other tools.

We are aware of this, and if you search the erlang list you'll find several
postings about this.

I've been struggling to define "best practise" for unit-testing,
dialyzing, edocing
etc. ie try and throw every tool at your code, but progress is slow.

It will be fixed in the goodness of time - who knows as I write this some brave
soul might download edoc and see to it that it uses the same type parser
as the dialyser and see to it that this is up-to-date with the main parser.

The trouble is that making (say) edoc consistent with the dialyzer might break
a lot of legacy edoc code - which upsets people.

The trouble is fundamental in nature.

If you make A and B and A and B are small rather useful tools, then A
and B will attract users and become big valuable tools.

At this stage you might notice an overlap in what A and B do - this would not
be noticed when A and B were small.

Bringing A into line with B could break legacy A code, and vice versa.

This is basically the problem with the entire documentation. We have legacy
XML annotations that are used in a tiny tiny fraction of the code. But complete
out-phasing means manually checking stuff that hasn't been touched for year.

Bringing stuff into line *without breaking the old stuff*  is very difficult.

All I can say is that we are aware of the problem and are trying to fix it.

/Joe




>
>
>> If you actually read the docs sequentially, front to back, they
>> absolutely *do* make a coherent whole.
>>
>
> I respectfully disagree.  I humbly submit further that you are not doing
> what I suggested by looking at the existing docs with a newb's eyes.
>
> --
> "Perhaps people don't believe this, but throughout all of the discussions of
> entering China our focus has really been what's best for the Chinese people.
> It's not been about our revenue or profit or whatnot."
> --Sergey Brin, demonstrating the emptiness of the "don't be evil" mantra.
>